ez-elements

ez-elements

ez-elements is a thin wrapper for the built-in HTMLElement class that aims to simplify writing imperative element creation and manipulation approachable in TypeScript.

If you find yourself writing a lot of document.createElement and dealing with the low-level built-in HTMLElement class then ez-elements can simplify a lot of the boilerplate code you're writing.

Getting Started

As an example, lets look at using document.createElement directly to create a div with two spans inside that is then appended to document.body:

const someDiv = document.createElement('div');
someDiv.classList.add('some-div');
const spanOne = document.createElement('span');
spanOne.classList.add('some-span');
spanOne.textContent = 'Hello ';
const spanTwo = document.createElement('span');
spanTwo.classList.add('some-span'); 
spanTwo.textContent = 'World';
someDiv.append(spanOne, spanTwo);
document.body.appendChild(someDiv);

By using the ez function from ez-elements we can simplify this to the following:

import { ez } from 'ez-elements';

let spanOne, spanTwo; // variables not required, but you can assign them inside the append
const someDiv = ez('div', 'some-div').append(
  spanOne = ez('span', 'some-span').setTextContent('Hello '),
  spanTwo = ez('span', 'some-span').setTextContent('World'),
).appendTo(document.body);

Install

npm install ez-elements --save

Alternatively, you can install just the parts of the package that you want:

• @ez-elements/core contains ez, EZElement, EZDiv and EZSpan.
• @ez-elements/inputs contains EZTextInput and EZButton.
• @ez-elements/jsx contains JSX.
• @ez-elements/shadow contains EZShadowElement and extractStyleContents.

Examples

Check out the Examples page.

How it works _{^{(and why you should care)}}

The ez function has the following interface:

• First argument is one of:
  • A HTML element tag name
  • A HTMLElement
  • An EZElement instance
• Optional second argument is one of:
  • a single class name string
  • array of class names as strings
  • an object of class name to active bool
• Returns an EZElement instance.

function ez<T extends keyof HTMLElementTagNameMap>(
    arg: T | HTMLElementTagNameMap[T] | EZElement<T>, 
    classes?: string | Array<string> | { [key: string]: boolean },
): EZElement<T>

You can also construct EZElement instances directly using:

const element = new EZElement('div');

Or extend EZElement to create components:

class SomeComponent extends EZElement<'div'> {
  constructor(text: string) {
    super('div');
    
    this.addClass('some-component').append(
        ez('span').setTextContent(text),
    );
  }
}

const instance = new SomeComponent('Hello World');
instance.appendTo(document.body);

The EZElement instance is a wrapper for a HTMLElement and provides a builder pattern interface to allow chaining, including appending/prepending children, appending to parents, adding classes, adding styles etc.

The reason you should care about what is happening under-the-hood is so that you can:

• Meaningfully debug issues relating to usage of the wrapper.
• Reason about the performance of your code without reading framework-specific guides or having a dedicated profiler/extension.
• Work around shortcomings of the wrapper where appropriate.

Intent

The intent of the wrapper is to be thin and as close to stateless as possible whilst remaining useful.

The priorities of the package are to enable your code to be (in descending priority order):

• Debuggable
• Readable
• Performant
• Brief (as little code as possible)

Development

This repository uses lerna to manage the multiple packages contained within it.

# Installs dependencies *and links the packages together using lerna*
npm install  

# In one terminal - watch and rebuild the packages upon changes
npm run watch

# In another terminal - start a parcel server that serves a  single page app with some examples
cd examples
npm start