1.0.0

A small web framework for a minimalistic development flow. Zero dependencies, no build step except for typescript compilation, and a simple virtual DOM implementation that is easy to understand and use. Autocompletion out of the box due to binding to lib.dom.d.ts.

vode

A vode is a representation of a virtual DOM node, which is a tree structure of HTML elements. It is written as tuple:

[TAG, PROPS?, CHILDREN...]

As you can see, it is a simple array with the first element being the tag name, the second element being an optional properties object, and the rest being child-vodes.

Component

type Component<S> = (s: S) => ChildVode<S>;

A Component<State> is a function that takes a state object and returns a Vode<State>. It is used to render the UI based on the current state.

// A full vode has a tag, properties, and children. props and children are optional.
const CompFooBar = (s) => [DIV, { class: "container" }, 
    
    // a child vode can be a string, which results in a text node
    [H1, "Hello World"], 
    
    // a vode can also be a self-closing tag
    [BR],
    
    // style object maps directly to the HTML style attribute
    [P, { style: { color: "red", fontWeight: "bold" } }, "This is a paragraph."],

    // class property has multiple forms
    [UL,
        [LI, {class: "class1 class2"}, "as string"],
        [LI, {class: ["class1", "class2"]}, "as array"],
        [LI, {class: {class1: true, class2: false}}, "as Record<string, boolean>"],
    ],

    // events get the state object as first argument
    // and the HTML event object as second argument
    [BUTTON, {
        // all on* events accept `Patch<State>`
        onclick: (state, evt) => {
            // objects returned by events are patched automatically
            return { counter: state.counter + 1 }; 
        },

        // you can set the patch object directly for events
        onmouseenter: {pointing: true},
        onmouseleave: {pointing: false},

        // a patch can be an async function
        onmouseup: async (state, evt) => {
            state.patch(loading: true);
            const result = await apiCall();
            return { title: result.data.title, loading: false };
        },

        // you can also use a generator function that yields patches
        onmousedown: async function* (state, evt) => {
            yield { loading: true }; 
            const result = await apiCall();
            yield { 
                body: result.data.body, 
                loading: false
            };
        },

        class: { bar: s.pointing }
    }, "Click me!"],
];

app

app is a function that takes a HTML node, an initial state object, and a render function (Component<State>).

const appNode = document.getElementById('APP-ID');
const initialState = {
    counter: 0,
    pointing: false,
    loading: false,
    title: '',
    body: '',
};
const patch = app<State>(appNode, initialState, (s) => CompFooBar(s));

It will render the initial state and update the DOM when patches are applied to the patch function or via events. All elements returnded by the render function are placed under appNode.

You can have multiple isolated app instances on a page, each with its own state and render function. The returned patch function from app can be used to synchronize the state between them.

memoization

To optimize performance, you can use memo(Array, Component) to cache the result of a component function. This is useful when the component does not depend on the state or when the state does not change frequently.

const CompMemoFooBar = (s) =>  [DIV, { class: "container" }, 
    [H1, "Hello World"], 
    [BR], 
    [P, "This is a paragraph."],
    
    // expensive component to render
    memo(
        // this array is shallow compared to the previous render
        [s.title, s.body], 
        // this is the component function that will be 
        // called only when the array changes
        (s) => {
            const list = [UL];
            for (let i = 0; i < 1000; i++) {
                list.push([LI, `Item ${i}`]);
            }
            return list;
        },
    )
];

state

The state is a singleton object that can be updated. A re-render happens when a patch object is supplied to the patch function or via event.

// type safe way to create the state object
const s = createState({
    counter: 0,
    pointing: false,
    loading: false,
    title: 'foo',
    body: '',
});

type State = typeof s;

app(appNode, s, ...); // after calling app(), the state object is bound to the appNode


s.title = 'Hello World'; // update state directly as it is a singleton (silent patch)

s.patch({}); // render patch

s.patch({ title: 'bar' }); // render patch with a change that is applied to the state 

s.patch((s) => ({body: s.body + ' baz'})); // render patch with a function that receives the state

s.patch(async function*(s){
    // you can also use a generator function that yields patches
    yield { loading: true };
    const result = await apiCall();
    yield { title: result.title, body: result.body };
    return { loading: false }; 
});

s.patch(null); // ignored, also: undefined, number, string, boolean, void

s.patch({ pointing: undefined }); // deletes the property from the state

Install

ESM

<!DOCTYPE html>
<html>
<head>
    <title>ESM Example</title>
</head>
<body>
    <div id="app"></div>
    <script type="module">
        import { app, createState, BR, DIV, INPUT, SPAN } from 'https://cdn.jsdelivr.net/npm/@ryupold/vode/dist/vode.min.mjs';

        const appNode = document.getElementById('app');

        app(appNode, { counter: 0 },
            (s) => [DIV,
                [INPUT, {
                    type: 'button',
                    onclick: { counter: s.counter + 1 },
                    value: 'Click me',
                }],
                [BR],
                [SPAN, { style: { color: 'red' } }, `${s.counter}`],
            ]
        );
    </script>
</body>
</html>

Classic

<!DOCTYPE html>
<html>
<head>
    <title>Classic Script Example</title>
    <script src="https://cdn.jsdelivr.net/npm/@ryupold/vode/dist/vode.min.js"></script>
</head>
<body>
    <div id="app"></div>
    <script>
        const appNode = document.getElementById('app');
        V.app(appNode, { counter: 0 },
            (s) => ["DIV",
                ["INPUT", {
                    type: 'button',
                    onclick: { counter: s.counter + 1 },
                    value: 'Click me',
                }
                ],
                ["BR"],
                ["SPAN", { style: { color: 'red' } }, `${s.counter}`],
            ]);
    </script>
</body>
</html>

NPM

# npm
npm install @ryupold/vode --save

# yarn
yarn add @ryupold/vode

# bun
bun add @ryupold/vode

index.html

<html>
<head>
    <title>Vode Example</title>
    <script type="module" src="main.js"></script>
</head>
<body>
    <div id="app"></div>
</body>
</html>

main.ts

import { app, createState, BR, DIV, INPUT, SPAN } from '@ryupold/vode';


const init = createState({
    counter: 0,
});

type State = typeof init;

const appNode = document.getElementById('app');

app<State>(appNode, init,
    (s: State) => [DIV,
        [INPUT, {
            type: 'button',
            onclick: { counter: s.counter + 1 },
            value: 'Click me',
        }],
        [BR],
        [SPAN, { style: { color: 'red' } }, `${s.counter}`],
    ]
);

Contributing

I was delighted by the simplicity of hyperapp, which inspired me to create this library.

Not planning to add more features, just keeping it simple and easy.

But if you find bugs or have suggestions, feel free to open an issue or a pull request.

License

MIT