literaljs

LiteralJS

~1kb JavaScript library for building user interfaces.

Documentation Index

• Features
• Getting Started
• Install LiteralJS
• How to use JSX in LiteralJS?
• JSX Markup Syntax
• Object Markup Syntax
• Lifecycle Events

API Functions

• component
  • props
  • methods
  • render
    • getState
    • setState
    • props
    • methods
• render
• h

$ microbundle
Build output to build:
      1.29 kB: index.js
      1.32 kB: index.m.js
      1.35 kB: index.umd.js

Features and stuff

• Small: Only around 1kb in size.
• Fast: Current and previous vDOM are diffed against each other for performant updates and rendering.
• Virtual DOM: Diffing occurs on state update for more efficient DOM updates.
• Flexible Syntax: Freedom to use JSX, Hyperscript, or Object syntax.
• Lifecycle Methods: All DOM elements have the ability to trigger mounted and unmounted lifecycle functions using built-in JavaScript MutationObservers.
• One Global Store: One source of truth which makes other state management libraries less of a need.

Getting Started

The easiest way of getting started is by cloning the LiteralJS starter application located here:

• LiteralJS Starter Application

Once you clone the project, you cd to the directory and run the following commands:

$ npm install
$ npm run dev
// OR
$ yarn
$ yarn dev

This command is setup to launch a browser window and you should see a landing page. The project is also partially setup to deploy to Netlify if you want. Just make sure to use the build-netlify command in the Netlify dashboard and set the deploy folder to dist.

Install

$ npm install literaljs

$ yarn add literaljs

Import

const Literal = require('literaljs');
// OR
import Literal from 'literaljs';
// OR
import { component, render, h } from 'literaljs';

ES6 Examples

You can use 3 types of markup in the render!

JSX

• How to use JSX in LiteralJS?

const Foo = component({
  render: ({ getState, setState }) => (
    <div class='container'>
      This is the Count: {getState().count}
      <button
        events={{
          type: 'click',
          action: () => {
            var state = getState();
            setState({ count: state.count + 1 });
          }
        }}>
        Click Me!
      </button>
    </div>
  )
});

render(foo, 'app', { count: 0 });

Hyper Script

const Foo = component({
  render: ({ getState, setState }) =>
    h('div', {
        class: 'container',
        text: `This is the Count: ${getState().count}`
      }, [
        h('button', {
          events: {
            type: 'click',
            action: () => {
              var state = getState();
              setState({ count: state.count + 1 });
            }
          }
        })
      ]
    );
});

render(foo, 'app', { count: 0 });

Objects

const Foo = component({
  render: ({ getState, setState }) => ({
    element: 'div',
    class: 'container',
    text: `This is the Count: ${getState().count}`,
    children: [
      {
        element: 'button',
        text: 'Click Me!',
        events: {
          type: 'click',
          action: () => {
            var state = getState();
            setState({ count: state.count + 1 });
          }
        }
      }
    ]
  })
});

render(foo, 'app', { count: 0 });

component

The component function accepts objects with the following keys:

• props
• methods
• render

component props

The props of a component is an object which can be passed with anything that is normally valid in a JavaScript Object. This can include any data or functions.

The only component that can not recieve props is the root component that is passed to the Literal.render function.

Example:

const Bar = component({
  render: ({ getState, setState, props }) => (
    <p>Total: {props.total}</p>
  )
});

const Foo = component({
  render: ({ getState, setState }) => (
    <div>{Bar({ props: { total: 9 }})}</div>
  )
});

component methods

The methods key of a component will accept a function which returns an object of other functions. Within the methods, you also have access to a components getState and setState functions which can be used accordingly. You also, have access to created methods directly within the render function.

Example:

component({
  methods: ({ getState, setState }) => ({
    increase: () => {
      const count = getState().count;
      setState({ count: count + 1 });
    }
  }),
  render: ({ getState, setState, methods: { increase }}) => (
      <button
        events={{
          type: 'click',
          action: () => increase()
        }}
      >
        Current Count: {getState().count}
      </button>
    )
});

component render

The render key of a component accepts a function that returns an JavaScript Object.

• Properties

JSX Markup Syntax

JSX in LiteralJS has some differentiation when it comes to other implementations like JSX in React.

The biggest differentiator in syntax from React JSX is that the class attribute is acceptable on JSX elements and events are passed as either an Array or Objects or a single Object.

Event Objects need a type and action which are explained here.

Anything can be considered acceptable as attributes and any keys that work with LiteralJS Object Markup Syntax also work in LiteralJS JSX markup.

Example Of Single Event:

component({
  methods: ({ getState, setState }) => ({
    increase: () => {
      const count = getState().count;
      setState({ count: count + 1 });
    }
  }),
  render: ({ getState, setState, methods: { increase }}) => (
      <button
        events={{
          type: 'click',
          action: () => increase()
        }}
      >
        Current Count: {getState().count}
      </button>
    )
});

Example Of Multiple Events:

component({
  methods: ({ getState, setState }) => ({
    increase: () => {
      const count = getState().count;
      setState({ count: count + 1 });
    }
  }),
  render: ({ getState, setState, methods: { increase }}) => (
      <button
        events={[
          {
            type: 'mounted',
            action: () => console.log('Button Mounted')
          },
          {
            type: 'click',
            action: () => increase()
          }
        ]}
      >
        Current Count: {getState().count}
      </button>
    )
});

Object Markup Syntax

Object Markup is currently written with Objects with the following specified keys or strings:

• element*
• text
• class
• id
• children
• events
  • lifecycle events

* = Required Key

element Key

The element key in the render function markup is the HTML node tag name as a String. For example, an element with the value

The element key is required when generating a new DOM node.

Example:

component({
  render: () => ({
    element: 'div',
  })
});
// Outputs: <div></div>

text Key

The text key in the render function markup accepts a String an will generate a text inside the element.

Example:

component({
  render: () => ({
    element: 'div',
    text: 'Hello World!'
  })
});
// Outputs: <div>Hello World!</div>

You can also include regular strings as children to create text nodes.

Example:

component({
  render: () => ({
    element: 'div',
    children: ['Hello World!']
  })
});
// Outputs: <div>Hello World!</div>

class Key

The class key in the render function markup is the HTML node class name as a String.

Example:

component({
  render: () => ({
    element: 'div',
    class: 'title'
  })
});
// Outputs: <div class="title"></div>

id Key

The id key in the render function markup is the HTML node class name as a String.

Example:

component({
  render: () => ({
    element: 'div',
    id: '2'
  })
});
// Outputs: <div id="2"></div>

children Key

The children key in the render function markup represet the childNodes of a given element or DOM Node. This key only accepts an Array of Objects or Strings. Each Object or in this Array can be another Object that represents a new DOM Node. You can also use Strings to represet Text nodes.

Example:

component({
  render: () => ({
    element: 'div',
    children: [
      'Count: ',
      {
        element: 'span'
        text: '0'
      }
    ]
  })
});
// Outputs: <div>Count: <span>0</span></div>

Events Key

The events key in the render function markup accepts either an Array of events or a single event Object.

An event object has two keys:

• type (Event Name)
• action (Function To Trigger)

Example:

// An Array Of Events
component({
  render: () => ({
    element: 'button',
    text: 'Click Me!',
    events: [
      {
        type: 'click'
        action: () => console.log('Hello World!')
      }
    ]
  })
});
// Output in Console: Hello World!
// OR
component({
  render: () => ({
    element: 'button',
    text: 'Click Me!',
    events: {
      type: 'click'
      action: () => console.log('Hello World!')
    }
  })
});

Lifecycle Events

Besides the common event handlers like click, there are two lifecycle events that LiteralJS includes that can be attached to any DOM node.

To do so, just name the type value unmounted or mounted` to trigger functions when a DOM node is first placed in the DOM or removed from the DOM.

Example: Example:

component({
  render: () => ({
    element: 'div',
    text: 'I have a life!',
    events: [
      {
        type: 'mounted'
        action: () => console.log('I\'m on the page!')
      },
      {
        type: 'unmounted'
        action: () => console.log('I\'m off the page!')
      }
    ]
  })
});

Other Keys Not Listed

Other keys are also accepted in a DOM object, such as data and other custom keys.

Properties

Within the render function of a component, you have access to other functions and objects:

• getState
• setState
• props
• methods

getState

The getState function of the components render method will allow you to access the global store of your application.

setState

The setState function of the components render method accepts an object which will allow you to set new values for particular pieces of state in the global store

props

The props object of the components render method can contain any number of data types and functions. The only componentthat cannot containpropsis the rootcomponentthat is passed to theLiteral.render` method.

methods

The methods object allow you to access other functions defined directly in the component. You can use this as a way to organize other pieces of logic and keep the render function much cleaner.

render

The Literal.render function is responsible for parsing the AST that is provided with components, injecting the generated markup into the specific DOM node, diffing any new changes based on state, and setting the default application state.

The Literal.render function can accept 3 arguments, one of which is optional.

• The root component.
• The String id of the DOM node to inject generated markup with.
• (Optional) The default state as an Object

Example:

Literal.render(component, 'app', { count: 0 });
// or
render(component, 'app');

h

The Literal.h function will generate specific LiteralJS Object Syntax.

Using JSX

If you want to use JSX, you can import the Literal.h function and install the JSX transform plugin and add the pragma option to your .babelrc file.

In .babelrc:

{
  "plugins": [["transform-react-jsx", { "pragma": "h" }]]
}

Some text editors and linters might also require the following at the top of the file to recognize that the file is using JSX:

/** @jsx h */