An agnostic, reactive & minimalist (3kb) JavaScript UI library with direct access to native DOM.
MIT License
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 💥. So you could take full advantage of native APIs & mix it with other libraries to gain superior performance & flexibility in the development process.
A 2-in-1 virtual-DOM & no-virtual-DOM approach if you will.
0️⃣ Zero tooling, 0️⃣ zero dependencies, 0️⃣ zero 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 against Vanilla JS, jQuery, React JS, Vue & more.
Official site: caldom.org
Documentation: caldom.org/docs/
Use it as a chainable DOM traverser and a manipulator, a lightweight jQuery alternative.
_("#output-1")
.append(
_("+h1").text("Hello World!")
);
//Short append
_( "#output-1", _("+p", "This is CalDOM.") );
Build reactive components. Use it as a lightweight React JS/Vue JS alternative. Not using classes, similar to React Hooks, but simpler.
let app = _().react(
{},
{
render: state =>
_( "+h1", `Hello ${state.name}` ) //This is XSS safe by design
}
)
_("#output-2", app );
//Edit below line to update state
app.state.name = "World Reactively 💥";
Also works as an extended ES6 class.
class HelloWorld extends _.Component{
constructor(state){
super();
this.react(state);
}
render(state){
return _("+div", [ //Can pass children as an array too
_( "+h1", "Hello " + state.name ),
_( "+p", ["The time is: ", state.time] )
]);
}
tick(){
this.state.time = new Date().toTimeString().substr(0, 8);
}
didMount(){
setInterval( () => this.tick(), 1000);
}
}
let app = new HelloWorld( { name: "World!", time: "" } );
_("#output-3", app);
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.
let app = _().react(
{},
{
render: state =>{
let div = document.createElement("div");
let heading = document.createElement("h1");
heading.textContent = `I'm a reactive ${state.name}`;
div.appendChild(heading);
//.elem gives you the direct Element
div.appendChild( _("+h2", "💥💥💥").elem )
return div;
}
}
)
_("#output-3-1", app );
app.state.name = "native DOM Element. 🙀";
Not a fan of rendering & virtual-DOM thingies? Use CalDOM to update() pre-defined HTML content reactively. CalDOM's API is inspired by jQuery.
let person_one = _("#person-1").react(
{},
{
update: function(state, person){
person.find(".name").text( state.name );
person.find(".age").text( state.age );
}
}
)
//CalDOM batches these 2 state updates to only render once.
person_one.state.name = "Jane Doe";
person_one.state.age = 22;
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.
class Person extends _.Component{
constructor(){
super();
this.react({ name: "John", likes: ["SpongeBob"] });
}
render(state){
return _("+div", [
//Saving a reference to the direct DOM Element
this.$.title = _( "+h1", `I'm ${state.name}` ).elem,
_( "+p", "I like " + state.likes.join(" & ") )
]);
}
update(state, person, changed_keys, changes_count){
if( changes_count != 1 || !("name" in changed_keys) )
// Too complex to update, proceed to render.
return true;
else //Update name directly using the DOM reference
this.$.title
.textContent = `I'm ${state.name} Directly. 🦄`;
}
}
let user = new Person();
_("#output-4", user );
user.state.likes.push( "Hulk" ); //This is handled by render()
setTimeout( () =>
user.state.name = "Jane" //This is handled by update()
, 1000);
CalDOM integrates seamlessly with Web Components. Use CalDOM to create stateful & reactive Web Components. It also accepts web components as inputs.
class CustomElement extends HTMLElement{
connectedCallback(){
let title = _().react(
{ msg: "Hello World!" },
{
render: state =>
_( "+h2", state.msg )
}
);
// Appending H2 as a child, keeping root intact
// this = <custom-element>
_( this, title );
//Just a shortcut to access state easily
this.state = title.state;
}
doSomething(){
alert("Cool Eh!");
}
}
//Registering custom element.
customElements.define("custom-element", CustomElement);
let hello = document.createElement("custom-element");
document.getElementById("output-5-1").appendChild( hello );
hello.state.msg = "I'm a Reactive, Stateful & Native Web Component. 🔥";
//Creating a new web component using CalDOM
_("#output-5-1").prepend( _("+custom-element") )
You can use these custom elements in HTML code natively as usual. Note that browser support for Web Components is relatively new (95%). The future looks bright! 🔮
<custom-element onclick="doSomething()">
</custom-element>
<custom-element onclick="state.msg = 'Native Web Components are awesome! ✌️'">
</custom-element>
Basic building box of CalDOM is just native Node/Element. Thus, making it compatible with almost any DOM library on the web.
class HelloJquery extends _.Component{
constructor(){
super();
this.react({ prompt: "" });
}
render(state){
//Creating element & attaching click event using jQuery
return $("<h1></h1>")
.text( state.prompt )
.click( () => state.prompt = "Hello from jQuery!")[0];
}
}
let app = new HelloJquery();
_("#output-6", app);
app.state.prompt = "Click Me!"
You can use a library like JS-DOM to implement a browser context on the server.
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
);
Visit caldom.org to experiment with many live code examples.
<script src="https://unpkg.com/caldom"></script>
CalDOM is using '_' variable as a global short-hand by default. To use a different alias, set window['_cal_dom_alias'] = 'different_alias' before loading it.
CalDOM is not attaching anything to the global environment when used as a module.
npm install caldom
//CalDOM also runs on Node JS with js-dom
const _ = require('caldom');
//RequireJS
requirejs( ["caldom"], function(_){} );
//ES6 Module
import _ from "./dist/caldom.min.mjs.js";
Your contributions are very welcome and thank you in advance. Please make sure to unit-test after changes.
Implement tests
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
Need to benchmark bigger implementations (Like in a spreadsheet where each cell is a sub-component?)
Currently, the entire source code is in one file. So there isn't a huge build process other than using uglify-js to minify it.
This simply build the .min.js & .min.mjs.js & related .map files in the ./dist/ folder.
# Install dev dependencies
npm install
# Build
npm run build
Tests and benchmarks sources are at the ./tests_and_benchmarks. CalDOM is using a brand new unit-testing & benchmarking framework called pFreak. Which was created as a side project of CalDOM.
Unit test results for the latest build is available at caldom.org/tests/
Initiate pFreak after installation to set sym links properly
pfreak init ./tests_and_benchmarks/internal/
pfreak init ./tests_and_benchmarks/external/
Unit Tests
npm test
or
pfreak test ./tests_and_benchmarks/internal/
Run benchmarks against other libraries (This takes a lot of time, you can run tasks selectively using flags.)
cd ./tests_and_benchmarks/external/
pfreak benchmark
refer pFreak's help for details
pfreak --help