An agnostic, reactive & minimalist (3kb) UI library
Tags: javascript, webdev, showdev, react
Published: 2021-07-16 14:23:27

Introducing CalDOM, an agnostic, reactive & minimalist (3kb) JavaScript UI library with direct access to native DOM.

Instead of pulling you into a library-specific magical world, CalDOM let you fully access the DOM directly while keeping the reactivity. A 2-in-1 Virtual-DOM & No-Virtual-DOM approach if you will.

So you could take full advantage of native APIs & mix it with other libraries to gain superior performance & flexibility in the development process.

CalDOM does not require any dependency or tooling. It does not introduce any new syntax. Just pure JS.

In essence, CalDOM is just a wrapper around the native Node/Element. The overall performance drop is about 0.04x compared to vanilla/pure JavaScript. This is based on averaged unit level benchmarks in handling single & multiple-element instances. [View Benchmark Results](https://caldom.org/benchmark/) against Vanilla JS, jQuery, React JS, Vue &amp; more.

Official site: [caldom.org](https://www.caldom.org)

## Hello World!
Use it as a chainable DOM traverser and a manipulator, a lightweight jQuery alternative.

We use _ (underscore) to access CalDOM.

{% codepen https://codepen.io/dumijay/pen/BaRRNya default-tab=js,result %}

## Hello World - Reactive
Build reactive components. Use it as a lightweight React JS/Vue JS alternative.

This example not using classes, similar to React Hooks, but simpler.

{% codepen https://codepen.io/dumijay/pen/OJmmVgV default-tab=js %}

## Hello World - Reactive (ES6)
Also works as an extended ES6 class.

{% codepen https://codepen.io/dumijay/pen/KKmmpym default-tab=js%}

## Reactive Native DOM Elements
Native DOM Node is a first-class citizen. Also, a CalDOM instance is just a wrapper around them. This agnostic interoperability allows for an infinite amount of powerful integrations.

{% codepen https://codepen.io/dumijay/pen/KKmmpoq default-tab=js%}

## Make existing HTML reactive
Not a fan of rendering & virtual-DOM thingies? Use CalDOM to update() pre-defined HTML content reactively. CalDOM's API is inspired by jQuery.

{% codepen https://codepen.io/dumijay/pen/BaRRoVY default-tab=js%}

## Summon the power of both worlds!
Efficiently update() the DOM directly and/or proceed to virtual-DOM render if it's more suitable. Use this.$ to hold direct DOM Node references. CalDOM keeps them in sync even when render() drastically alter the DOM structure.

{% codepen https://codepen.io/dumijay/pen/GRmmpXM default-tab=js%}

## Use HTML to create
Similar to JSX, but with vanilla HTML & JavaScript. No compilers required.

{% codepen https://codepen.io/dumijay/pen/bGWWVOj default-tab=js%}

## You can even make jQuery reactive
Basic building box of CalDOM is just native Node/Element. Thus, making it compatible with almost any DOM library on the web.

{% codepen https://codepen.io/dumijay/pen/GRmmpzO default-tab=js%}

## Todo App - Non Reactive
CalDOM does not dictate your coding style or approach. It's super flexible & scalable from a single element to large nested implementations.

{% codepen https://codepen.io/dumijay/pen/qBmmOwa default-tab=js%}

## Todo App - Reactive
CalDOM renders a virtual-DOM and efficiently updates only changed elements in the actual DOM.

Multiple renders are batched to only run once.

{% codepen https://codepen.io/dumijay/pen/QWvvjRz default-tab=js%}

## Todo App - Multiple Nested Reactive Components
CalDOM plays nicely with nested reusable reactive components and takes care of all DOM updates efficiently.

No matter how deeply nested, components only get re-rendered if their state is changed.

{% codepen https://codepen.io/dumijay/pen/wvddKLx default-tab=js%}

## CalDOM also runs on Node JS
You can use a library like [JS-DOM](https://github.com/jsdom/jsdom) to implement a browser context on the server.

```js
const { JSDOM } = require("jsdom"); 

//Set window in the global scope
window = new JSDOM().window;

const _ = require("caldom");

class ServerApp extends _.Component{

    constructor(){
        super();

        this.react( { msg: "" } );
    }

    render(state){
        return _("+p", state.msg)
            .css("color", "#199646")
    }
}

let app = new ServerApp();
_("body", app);

app.react( { msg: "Hello from NodeJS " + process.version  } );

//Saving generated HTML by the component to a file
require("fs").writeFileSync(
    "static_content.html", 
    window.document.body.innerHTML 
);
```

Fetching and rendering content generated in the server.

{% codepen https://codepen.io/dumijay/pen/KKmmVQw default-tab=js%}

Multiple element instances, built-in XPath support & there is much more packed in this tiny 3KB (min.gzip) library.

Check out [caldom.org](https://caldom.org)

Please note that I did not use classes to keep the examples simple without HTML & CSS. But in practice, always prefer using external CSS over directly setting CSS on elements due to obvious reasons. CalDOM has addClass(), removeClass() methods to facilitate this.

# Get Started

## CDN

```html
<script src="https://unpkg.com/caldom"></script>
```

## Use it as a Module
CalDOM is not attaching anything to the global environment when used as a module.

```sh
npm install caldom
```

```js
//CalDOM also runs on Node JS with js-dom
const _ = require('caldom');
```

```js
//RequireJS
requirejs( ["caldom"], function(_){} );
```

```js
//ES6 Module
import _ from "./dist/caldom.min.mjs.js";
```

# Contributing
It's great if you could contribute to the project. It's open-source (MIT licenced) & available on [GitHub](https://github.com/dumijay/CalDom).

## Key Principles

* Performance, being agnostic(interoperability with native DOM) & minimalism is prioritized above all.
* The richness in short-hand methods and features is secondary.
* Supporting legacy browsers is not a priority.

## To-Do
* ~~Implement tests~~
    * Need to expand the variety of tests to different use cases. (Currently, it's biased towards my personal coding style).
* A beginner-friendly documentation/guide. Current one is too technical.
* Implement helpful debug outputs for the development version.
* Thorough browser version tests.
* Further optimize virtual DOM diffing algorithm. [See benchmark here](https://caldom.org/benchmark/)
    * The diffing algorithm is just 140+ lines of code.
    * I believe there is so much room for improvement if some bright minds look at it from a fresh angle.
* Need to benchmark bigger implementations.

___

That’s all the technical stuff. Phew! :)

This is the first time I’m publishing something like this. This was a simple jQuery alternative I made myself years ago & kept on improving it slowly. Worked really hard during the last few months to add reactivity and get it to this level.
Please let me know what you think. What’s bad, what’s good and your suggestions to improve it.

I honestly don’t know where this will lead. Probably all of this is just for nothing. The world has enough UI libraries already. Duh!. I decided to make my own mini jQuery years ago because I wanted a lightweight library. Also, I wanted to stay close to the native DOM API & vanilla JavaScript. Looking back, it paid really well. Then React & Vue JS happened.

In my opinion, the reactive UI approach bought a huge productivity improvement from the perspective of the developer. Also, it enabled a lot of beginner developers to navigate the programming landscape more easily.

However, this shift also moved people away from the core stuff that’s happening under the hood. As a result, sometimes we have to struggle a lot to find solutions within the library’s limits, which are sometimes hilariously dead simple & performant to implement with native APIs.

CalDOM tries to solve this by being 100% interoperable with the native DOM. I hope this will be helpful for developers with similar requirements.