shablon 0.0.1-rc.1

package/LICENSE.md

@@ -0,0 +1,14 @@
+Zero-Clause BSD (0BSD)
+
+Copyright (c) 2025 - present, Gani Georgiev
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+Shablon - No-build JavaScript frontend framework
+======================================================================
+
+> [!CAUTION]
+>  This is mostly an experiment created for the planned [PocketBase](https://github.com/pocketbase/pocketbase) UI rewrite to allow frontend plugins support.
+>
+> **Don't use it yet - it hasn't been actually tested in real applications and it may change without notice!**
+
+**Shablon** _("template" in Bulgarian)_ is a ~5KB JS framework that comes with deeply reactive state management, plain JS extendable templates and hash-based router.
+
+Shablon has very small learning curve (**4 main exported functions**) and it is suitable for building Single-page applications (SPA):
+
+- State: `store(obj)` and `watch(callback)`
+- Template: `t.[tag](attrs, ...children)`
+- Router: `router(routes, options)`
+
+There is no dedicated "component" structure. Everything is essentially plain DOM elements sprinkled with a little reactivity.
+
+Below is an example _Todos list "component"_ to see how it looks:
+
+```js
+function todos() {
+    const data = store({
+        todos: [],
+        newTitle: "",
+    })
+
+    // external watcher
+    const w = watch(() => {
+        console.log("new title:", data.newTitle)
+    })
+
+    return t.div({ className: "todos-list", onunmount: () => w.unwatch() },
+        t.h1({ textContent: "Todos" }),
+        t.ul({ style: "margin: 20px 0" },
+            () => {
+                if (!data.todos.length) {
+                    return t.li({ rid: "notodos", textContent: "No todos." })
+                }
+
+                return data.todos.map((todo) => {
+                    return t.li({ rid: todo, textContent: () => todo.title })
+                })
+            }
+        ),
+        t.hr(),
+        t.input({ type: "text", value: () => data.newTitle, oninput: (e) => data.newTitle = e.target.value }),
+        t.button({ textContent: "Add", onclick: () => data.todos.push({ title: data.newTitle }) })
+    )
+}
+
+document.getElementById("app").replaceChildren(todos());
+```
+
+<details>
+
+<summary>
+Example Svelte 5 equivalent code for comparison
+
+_Shablon is not as pretty as Svelte but it strives for similar developer experience._
+</summary>
+
+
+```svelte
+<script>
+    let todos = $state([])
+    let newTitle = $state("")
+
+    // external watcher
+    // note: no need to manually call "untrack" because Svelte does it automatically on component unmount
+    $effect(() => {
+        console.log("new title:", newTitle)
+    })
+</script>
+
+<div class="todos-list">
+    <h1>Todos</h1>
+    <ul style="margin: 20px 0">
+        {#each todos as todo}
+            <li>{todo.title}</li>
+        {:else}
+            <li>No todos.</li>
+        {/each}
+    </ul>
+    <hr>
+    <input type="text" bind:value="{newTitle}">
+    <button onclick="{() => todos.push({ title: newTitle })}">Add</button>
+</div>
+```
+
+</details>
+
+
+
+## Installation
+
+> You can also check the [`example` folder](https://github.com/ganigeorgiev/shablon/tree/master/example) for a showcase of a minimal SPA with 2 pages.
+
+#### Global via script tag (browsers)
+
+The default [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) bundle will load all exported Shablon functions in the global context.
+You can find the bundle file at [`dist/shablon.iife.js`](https://github.com/ganigeorgiev/shablon/blob/master/dist/shablon.iife.js) (or use a CDN pointing to it):
+
+```html
+<!-- <script src="https://cdn.jsdelivr.net/gh/ganigeorgiev/shablon@master/dist/shablon.iife.js"></script> -->
+<script src="/path/to/dist/shablon.iife.js"></script>
+<script type="text/javascript">
+    const data = store({ count: 0 })
+    ...
+</script>
+```
+
+#### ES module (browsers and npm)
+
+Alternatively, you can load the package as ES module by using the [`dist/shablon.es.js`](https://github.com/ganigeorgiev/shablon/blob/master/dist/shablon.es.js) file.
+
+<!-- Alternatively, you can load the package as ES module either by using the [`dist/shablon.es.js`](https://github.com/ganigeorgiev/shablon/blob/master/dist/shablon.es.js) file or
+importing it from [npm](https://www.npmjs.com/package/shablon). -->
+
+- browsers:
+    ```html
+    <!-- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules -->
+    <script type="module">
+        import { t, store, watch, router } from "/path/to/dist/shablon.es.js"
+
+        const data = store({ count: 0 })
+        ...
+    </script>
+    ```
+<!--
+- npm (`npm -i shablon`):
+    ```js
+    import { t, store, watch, router } from "shablon"
+
+    const data = store({ count: 0 })
+    ...
+    ```
+ -->
+## API
+<details>
+<summary><strong id="api.store">store(obj)</strong></summary>
+
+`store(obj)` returns a reactive `Proxy` of the specified plain object.
+
+The keys of an `obj` must be "stringifiable" because they are used internally to construct a path to the reactive value.
+
+The values can be any valid JS value, including nested arrays and objects (aka. it is recursively reactive).
+
+Getters are also supported and can be used as reactive computed properties.
+The value of a reactive getter is "cached", meaning that even if one of the getter dependency changes, as long as the resulting value is the same there will be no unnecessary watch events fired.
+
+Multiple changes from one or many stores are also automatically batched in a microtask. For example:
+
+```js
+const data = store({ age: 49, activity: "work" })
+
+watch(() => {
+    console.log("age", data.age)
+    console.log("activity", data.activity)
+})
+
+// changing both fields will trigger the watcher only once
+data.age++
+data.activity = "rest"
+```
+
+</details>
+
+
+<details>
+<summary><strong id="api.watch">watch(callback)</strong></summary>
+
+Watch registers a callback function that fires once on initialization and
+every time any of its `store` reactive dependencies change.
+
+It returns a "watcher" object that could be used to `unwatch` the registered listener.
+
+For example:
+
+```js
+const data = store({ count: 0 })
+
+const w = watch(() => console.log(data.count))
+
+data.count++ // triggers watch update
+
+w.unwatch()
+
+data.count++ // doesn't trigger watch update
+```
+
+Note that for reactive getters, initially the watch callback will be invoked twice because we register a second internal watcher to cache the getter value.
+
+</details>
+
+
+<details>
+<summary><strong id="api.t">t.[tag](attrs, ...children)</strong></summary>
+
+`t.[tag](attrs, ...children)` constructs and returns a new DOM element (aka. `document.createElement(tag)`).
+
+`tag` could be any valid HTML element name - `div`, `span`, `hr`, `img`, registered custom web component, etc.
+
+`attrs` is an object where the keys are:
+- valid element's [JS property](https://developer.mozilla.org/en-US/docs/Web/API/Element#instance_properties)
+    _(note that some HTML attribute names are different from their JS property equivalent, e.g. `class` vs `className`, `for` vs `htmlFor`, etc.)_
+- regular or custom HTML attribute if it has `html-` prefix _(it is stripped from the final attribute)_, e.g. `html-data-name`
+
+The attributes value could be a plain JS value or reactive function that returns such value _(e.g. `() => data.count`)_.
+
+`children` is an optional list of child elements that could be:
+- plain text (inserted as `TextNode`)
+- single tag
+- array of tags
+- reactive function that returns any of the above
+
+When a reactive function is set as attribute value or child, it is invoked only when the element is mounted and automatically "unwatched" on element removal _(with slight debounce to minimize render blocking)_.
+
+**Lifecycle attributes**
+
+Each constructed tag has 3 additional optional lifecycle attributes:
+
+- `onmount: func` - optional callback called when the element is inserted in the DOM
+- `onunmount: func` - optional callback called when the element is removed from the DOM
+- `rid: any` - "replacement id" is an identifier based on which we can decide whether to reuse the element or not during rerendering (e.g. on list change); the value could be anything comparable with `==`
+
+</details>
+
+
+<details>
+<summary><strong id="api.router">router(routes, options)</strong></summary>
+
+`router(routes, options = { fallbackPath: "#/", transition: true })` initializes a hash-based client-side router by loading the provided routes configuration and listens for hash navigation changes.
+
+`routes` is a key-value object where:
+- the key must be a string path such as `#/a/b/{someParam}`
+- value is a route handler function that executes every time the page hash matches with the route's path
+    _(the route handler can return a "destroy" function that is invoked when navigating away from that route)_
+
+Note that by default the router expects to have at least one "#/" route that will be also used as fallback in case the user navigate to a missing page.
+
+For example:
+
+```js
+router({
+    "#/": (route) => {
+        document.getElementById(app).replaceChildren(
+            t.div({ textContent: "Homepage!"})
+        )
+    },
+    "#/users/{id}": (route) => {
+        document.getElementById(app).replaceChildren(
+            t.div({ textContent: "User " + route.params.id })
+        )
+        return () => { console.log("cleanup...") }
+    },
+})
+```
+
+</details>
+
+
+## Performance and caveats
+
+No extensive testing or benchmarks have been done yet but for the simple cases it should perform as fast as it could get because we update only the targeted DOM attribute when possible _(furthermore multiple store changes are auto batched per microtask to ensure that watchers are not invoked unnecessary)_.
+
+For example, the expression `t.div({ textContent: () => data.title })` is roughly the same as the following pseudo-code:
+
+```js
+const div = document.createElement("div")
+div.textContent = data.title
+
+function onTitleChange() {
+    div.textContent = data.title
+}
+```
+
+Conditional rendering tags as part of a reactive child function is a little bit more complicated though.
+By default when such function runs due to a store dependency change, the old children will be removed and the new ones will be inserted on every call of that function which could be unnecessary if the tags hasn't really changed.
+
+To avoid this you can specify the `rid` attribute which instructs Shablon to reuse the same element if the old and new `rid` are the same minimizing the DOM operations. For example:
+
+```js
+const data = store({ count: 0, list: ["a", "b", "c"] })
+
+// ALWAYS replace the child tags on every data.count or data.list change
+t.div({ className: "bad"},
+    () => {
+        if (data.count < 2) {
+            return t.strong({}, "Not enough elements")
+        }
+        return data.list.map((item) => t.div({}, item))
+    }
+)
+
+// replace the child tags on data.count or data.list change
+// ONLY if the tags "rid" attribute has changed
+t.div({ className: "good"},
+    () => {
+        if (data.count < 2) {
+            return t.strong({ rid: "noelems" }, "Not enough elements")
+        }
+        return data.list.map((item) => t.div({ rid: item }, item))
+    }
+)
+```
+
+Other things that could be a performance bottleneck are the lifecycle attributes (`onmount`, `onunmount`) because currently they rely on a global `MutationObserver` which could be potentially slow for deeply nested elements due to the nature of the current recursive implementation _(this will be further evaluated during the actual integration in PocketBase)_.
+
+
+## Security
+
+Shablon **DOES NOT** perform any explicit escaping on its own and it relies on:
+
+- modern browsers to perform TextNode _(when a child is a plain string)_ and attributes value escaping out of the box for us
+- developers to use the appropriate safe JS properties (e.g. `textContent` instead of `innerHTML`)
+
+**There could be some gaps and edge cases so I strongly recommend registering a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) either as `meta` tag or HTTP header to prevent XSS attacks.**
+
+
+## Why Shablon?
+
+If you are not sure why would you use Shablon instead of Svelte, Lit, Vue, etc., then I'd suggest to simply pick one of the latter because they usually have a lot more features, can offer better ergonomics and have abundance of tutorials.
+
+Shablon was created for my own projects, and more specifically for PocketBase in order to allow writing dynamically loaded dashboard UI plugins without requiring a Node.js build step.
+Since I didn't feel comfortable maintaining UI plugins system on top of another framework with dozens other dependencies that tend to change in a non-compatible way over time, I've decided to try building my own with minimal API surface and that can be safely "frozen".
+
+Shablon exists because:
+
+- it can be quickly learned (4 main exported functions)
+- it has minimal "magic" and no unsafe-eval (aka. it is Content Security Policy friendly)
+- no IDE plugin or custom syntax highlighter is needed (it is plain JavaScript)
+- the templates return regular [JS `Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) allowing direct mutations
+- it doesn't require build step and can be imported in the browser with a regular script tag
+- it has no external dependencies and doesn't need to be updated frequently
+- it is easy to maintain on my own _(under 2000 LOC with tests)_
+
+
+## Contributing
+
+Shablon is free and open source project licensed under the [Zero-Clause BSD License](https://github.com/ganigeorgiev/shablon/blob/master/LICENSE.md) _(no attribution required)_.
+
+Feel free to report bugs, but feature requests are not welcomed.
+
+**There are no plans to extend the project scope and once a stable PocketBase release is published it could be considered complete.**

package/index.js

@@ -0,0 +1,3 @@
+export * from "./src/state.js";
+export * from "./src/template.js";
+export * from "./src/router.js";

package/package.json

@@ -0,0 +1,34 @@
+{
+    "version": "0.0.1-rc.1",
+    "name": "shablon",
+    "description": "No-build JavaScript framework for Single-page applications",
+    "author": "Gani Georgiev",
+    "license": "MIT",
+    "type": "module",
+    "exports": "./index.js",
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/ganigeorgiev/shablon.git"
+    },
+    "keywords": [
+        "frontend",
+        "js-framework",
+        "no-build",
+        "spa"
+    ],
+    "scripts": {
+        "build": "rolldown -c",
+        "format": "npx prettier ./src --write",
+        "prepublishOnly": "npm run build"
+    },
+    "devDependencies": {
+        "jsdom": "^26.0.0",
+        "prettier": "^3.6.2",
+        "rolldown": "^1.0.0-beta.44"
+    },
+    "prettier": {
+        "tabWidth": 4,
+        "printWidth": 90,
+        "bracketSameLine": true
+    }
+}

package/src/router.js

@@ -0,0 +1,134 @@
+/**
+ * @callback routeHandler
+ * @param {{params:Object.<string,string>, query:Object.<string,string[]>, path:string, regex:string, pattern:string, handler:Function}} route
+ * @return {Function|void} Optional destroy function.
+ */
+/**
+ * Router set up a hash-based client-side router by loading the
+ * provided routes configuration and listens for hash navigation changes.
+ *
+ * `routes` is a key-value object where:
+ * - the key must be a string path such as "#/a/b/{someParam}"
+ * - value is a route handler function that executes every time the page hash matches with the route's path.
+ *     The route handler can return a "destroy" function that will be invoked when navigating away from that route.
+ *
+ * Note that by default it expects to have at least one "#/" route that will be
+ * also used as fallback in case the user navigate to a page that is not defined.
+ *
+ * Example:
+ *
+ * ```js
+ * router({
+ *     "#/": (route) => {
+ *         document.getElementById(app).replaceChildren(
+ *             t.div({ textContent: "Homepage!"})
+ *         )
+ *     },
+ *     "#/users/{id}": (route) => {
+ *         document.getElementById(app).replaceChildren(
+ *             t.div({ textContent: "User " + route.params.id })
+ *         )
+ *     },
+ * })
+ * ```
+ *
+ * @param {Object.<string, routeHandler>} routes
+ * @param {Object} [options]
+ * @param {string} [options.fallbackPath]
+ * @param {boolean} [options.transition]
+ */
+export function router(routes, options = { fallbackPath: "#/", transition: true }) {
+    let defs = prepareRoutes(routes);
+
+    let prevDestroy;
+
+    let onHashChange = () => {
+        let path = window.location.hash || options.fallbackPath;
+
+        let route =
+            findActiveRoute(defs, path) || findActiveRoute(defs, options.fallbackPath);
+        if (!route) {
+            console.warn("no route found");
+            return;
+        }
+
+        let navigate = async () => {
+            try {
+                await prevDestroy?.();
+                prevDestroy = await route.handler(route);
+            } catch (err) {
+                console.warn("Route navigation failed:", err);
+            }
+        };
+
+        if (options.transition && document.startViewTransition) {
+            document.startViewTransition(navigate);
+        } else {
+            navigate();
+        }
+    };
+
+    window.addEventListener("hashchange", onHashChange);
+
+    onHashChange();
+}
+
+function findActiveRoute(defs, path) {
+    for (let def of defs) {
+        let match = path.match(def.regex);
+        if (!match) {
+            continue;
+        }
+
+        // extract query params (the value is always stored as array)
+        let query = {};
+        let rawQuery = path.split("?")?.[1];
+        if (rawQuery) {
+            let searchParams = new URLSearchParams(rawQuery);
+            for (let [key, value] of searchParams.entries()) {
+                if (!Array.isArray(query[key])) {
+                    query[key] = query[key] ? [query[key]] : [];
+                }
+                query[key].push(value);
+            }
+        }
+
+        return Object.assign(
+            {
+                path: path,
+                query: query,
+                params: match.groups || {},
+            },
+            def,
+        );
+    }
+}
+
+function prepareRoutes(routes) {
+    let defs = [];
+
+    for (let path in routes) {
+        let parts = path.split("/");
+        for (let i in parts) {
+            if (
+                parts[i].length > 2 &&
+                parts[i].startsWith("{") &&
+                parts[i].endsWith("}")
+            ) {
+                // param
+                parts[i] = "(?<" + parts[i].substring(1, parts[i].length - 1) + ">\\w+)";
+            } else {
+                // regular path segment
+                parts[i] = RegExp.escape(parts[i]);
+            }
+        }
+
+        defs.push({
+            regex: new RegExp("^" + parts.join("\\/") + "(?:[\?\#].*)?$"),
+            pattern: path,
+            handler: routes[path],
+        });
+    }
+
+    return defs;
+}

package/src/state.js

@@ -0,0 +1,304 @@
+let activeWatcher;
+
+let flushQueue = new Set();
+let allWatchers = new Map();
+let toRemove = [];
+let cleanTimeoutId;
+
+let idSym = Symbol();
+let parentSym = Symbol();
+let childrenSym = Symbol();
+let pathsSubsSym = Symbol();
+let unwatchedSym = Symbol();
+let onRemoveSym = Symbol();
+
+/**
+ * Watch registers a callback function that fires on initialization and
+ * every time any of its `store` reactive dependencies changes.
+ *
+ * Returns a "watcher" object that could be used to `unwatch()` the registered listener.
+ *
+ * Example:
+ *
+ * ```js
+ * const data = store({ count: 0 })
+ *
+ * const sub = watch(() => console.log(data.count))
+ *
+ * data.count++ // triggers watch update
+ *
+ * sub.unwatch()
+ *
+ * data.count++ // doesn't trigger watch update
+ * ```
+ *
+ * @param  {Function} callback
+ * @return {{unwatch:Function, last:any, run:Function}}
+ */
+export function watch(callback) {
+    let watcher = {
+        [idSym]: "" + Math.random(),
+    };
+
+    allWatchers.set(watcher[idSym], watcher);
+
+    watcher.run = () => {
+        // nested watcher -> register previous watcher as parent
+        if (activeWatcher) {
+            watcher[parentSym] = activeWatcher[idSym];
+
+            // store immediate children references for quicker cleanup
+            activeWatcher[childrenSym] = activeWatcher[childrenSym] || [];
+            activeWatcher[childrenSym].push(watcher[idSym]);
+        }
+
+        activeWatcher = watcher;
+        watcher.last = callback();
+        activeWatcher = allWatchers.get([watcher[parentSym]]); // restore parent ref (if any)
+    };
+
+    watcher.unwatch = function () {
+        watcher[unwatchedSym] = 1;
+
+        toRemove.push(watcher[idSym]);
+
+        if (cleanTimeoutId) {
+            clearTimeout(cleanTimeoutId);
+        }
+
+        // note: debounced and executed as separate task to minimize blocking unmount rendering
+        cleanTimeoutId = setTimeout(() => {
+            for (let id of toRemove) {
+                removeWatcher(id);
+            }
+
+            toRemove = [];
+            cleanTimeoutId = null;
+        }, 50);
+    };
+
+    watcher.run();
+
+    return watcher;
+}
+
+function removeWatcher(id) {
+    let w = allWatchers.get(id);
+
+    w?.[onRemoveSym]?.();
+
+    if (w?.[childrenSym]) {
+        for (let childId of w[childrenSym]) {
+            removeWatcher(childId);
+        }
+        w[parentSym] = null;
+        w[childrenSym] = null;
+    }
+
+    if (w?.[pathsSubsSym]) {
+        for (let subset of w[pathsSubsSym]) {
+            if (subset.has(id)) {
+                subset.delete(id);
+            }
+        }
+        w[pathsSubsSym] = null;
+    }
+
+    allWatchers.delete(id);
+}
+
+// -------------------------------------------------------------------
+
+/**
+ * Creates a new deeply reactive store object that triggers `watch`
+ * update on change of a specific watched store property.
+ *
+ * Example:
+ *
+ * ```js
+ * const data = store({ count: 0, name: "test" })
+ *
+ * watch(() => console.log(data.count)) // should fire twice: 0 (initial), 1 (on increment)
+ *
+ * data.count++
+ * ```
+ *
+ * Getters are also supported out of the box and they are invoked every
+ * time when any of their dependencies change.
+ * If a getter is used in a reactive function, its resulting value is cached,
+ * aka. if the final value hasn't changed it will not trigger an unnecessery reactive update.
+ *
+ * Multiple changes from one or many stores are also automatically batched in a microtask.
+ *
+ * @param  {Object} obj
+ * @return {Object} Proxied object.
+ */
+export function store(obj) {
+    let pathWatcherIds = new Map();
+
+    return createProxy(obj, pathWatcherIds);
+}
+
+function createProxy(obj, pathWatcherIds) {
+    // extract props info to identify getters
+    let descriptors =
+        typeof obj == "object" && !Array.isArray(obj)
+            ? Object.getOwnPropertyDescriptors(obj)
+            : {};
+
+    let handler = {
+        get(obj, prop, target) {
+            // getter?
+            let getterProp;
+            if (descriptors[prop]?.get) {
+                // if not invoked inside a watch function, call the original
+                // getter to ensure that an up-to-date value is computed
+                if (!activeWatcher) {
+                    return descriptors[prop]?.get?.call(obj);
+                }
+
+                getterProp = prop;
+
+                // replace with an internal "@prop" property so that
+                // reactive statements can be cached
+                prop = "@" + prop;
+            }
+
+            // directly return symbols and functions (pop, push, etc.)
+            if (typeof prop == "symbol" || typeof obj[prop] == "function") {
+                return obj[prop];
+            }
+
+            // wrap child object or array as sub store
+            if (
+                typeof obj[prop] == "object" &&
+                obj[prop] !== null &&
+                !obj[prop][parentSym]
+            ) {
+                obj[prop][parentSym] = [obj, prop];
+                obj[prop] = createProxy(obj[prop], pathWatcherIds);
+            }
+
+            // register watch subscriber (if any)
+            if (activeWatcher) {
+                let currentPath = getPath(obj, prop);
+                let activeWatcherId = activeWatcher[idSym];
+
+                let subs = pathWatcherIds.get(currentPath);
+                if (!subs) {
+                    subs = new Set();
+                    pathWatcherIds.set(currentPath, subs);
+                }
+                subs.add(activeWatcherId);
+
+                activeWatcher[pathsSubsSym] = activeWatcher[pathsSubsSym] || new Set();
+                activeWatcher[pathsSubsSym].add(subs);
+
+                // register a child watcher to update the custom getter prop replacement
+                // (should be removed automatically with the removal of the parent watcher)
+                if (
+                    getterProp &&
+                    !descriptors[getterProp]._watchers?.has(activeWatcherId)
+                ) {
+                    descriptors[getterProp]._watchers =
+                        descriptors[getterProp]._watchers || new Set();
+                    descriptors[getterProp]._watchers.add(activeWatcherId);
+
+                    let getFunc = descriptors[getterProp].get.bind(obj);
+
+                    let getWatcher = watch(() => (target[prop] = getFunc()));
+
+                    getWatcher[onRemoveSym] = () => {
+                        descriptors[getterProp]?.watchers?.delete(watcherId);
+                    };
+                }
+            }
+
+            return obj[prop];
+        },
+        set(obj, prop, value) {
+            if (typeof prop == "symbol") {
+                obj[prop] = value;
+                return true;
+            }
+
+            let oldValue = obj[prop];
+            obj[prop] = value;
+
+            // trigger only on value change
+            // (exclude length since the old value would have been already changed on access)
+            if (value != oldValue || prop === "length") {
+                callWatchers(obj, prop, pathWatcherIds);
+            }
+
+            return true;
+        },
+        deleteProperty(obj, prop) {
+            if (typeof prop != "symbol") {
+                callWatchers(obj, prop, pathWatcherIds);
+
+                let currentPath = getPath(obj, prop);
+                if (pathWatcherIds.has(currentPath)) {
+                    pathWatcherIds.delete(currentPath);
+                }
+            }
+
+            delete obj[prop];
+
+            return true;
+        },
+    };
+
+    return new Proxy(obj, handler);
+}
+
+function getPath(obj, prop) {
+    let currentPath = prop;
+
+    let parentData = obj?.[parentSym];
+    while (parentData) {
+        currentPath = parentData[1] + "." + currentPath;
+        parentData = parentData[0][parentSym];
+    }
+
+    return currentPath;
+}
+
+function callWatchers(obj, prop, pathWatcherIds) {
+    let currentPath = getPath(obj, prop);
+
+    let watcherIds = pathWatcherIds.get(currentPath);
+
+    if (!watcherIds) {
+        return true;
+    }
+
+    for (let id of watcherIds) {
+        flushQueue.add(id);
+
+        if (flushQueue.size != 1) {
+            continue;
+        }
+
+        queueMicrotask(() => {
+            let watcher;
+            for (let runId of flushQueue) {
+                watcher = allWatchers.get(runId);
+                if (!watcher || watcher[unwatchedSym]) {
+                    continue;
+                }
+
+                // if both parent and child watcher exists,
+                // execute only the parent because the child
+                // watchers will be invoked automatically
+                if (watcher[parentSym] && flushQueue.has(watcher[parentSym])) {
+                    continue;
+                }
+
+                watcher.run();
+            }
+
+            flushQueue.clear();
+        });
+    }
+}

package/src/template.js

@@ -0,0 +1,405 @@
+import { watch } from "./state.js";
+
+/**
+ * Proxy object for creating and returning a new HTML element in the format `t.[tag](attrs, ...children)`.
+ *
+ * For example:
+ *
+ * ```js
+ * t.div({ className: "test-div" },
+ *     t.span({ textContent: "child1"}),
+ *     t.span({ textContent: "child2"}),
+ * )
+ * ```
+ *
+ * `attrs` is an object where the keys are:
+ * - valid element's [JS property](https://developer.mozilla.org/en-US/docs/Web/API/Element#instance_properties)
+ *   _(note that some HTML attribute names are different from their JS property equivalent, e.g. `class` vs `className`, `for` vs `htmlFor`, etc.)_
+ * - regular or custom HTML attribute if it has `html-` prefix _(it is stripped from the final attribute)_, e.g. `html-data-name`
+ *
+ * The attributes value could be a plain JS value or reactive function that returns such value _(e.g. `() => data.count`)_.
+ *
+ * `children` is an optional list of child elements that could be:
+ * - plain text (inserted as `TextNode`)
+ * - single tag
+ * - array of tags
+ * - reactive function that returns any of the above
+ *
+ * Each constructed tag has 3 additional optional lifecycle attributes:
+ * - `onmount: func` - optional callback called when the element is inserted in the DOM
+ * - `onunmount: func` - optional callback called when the element is removed from the DOM
+ * - `rid: any` - "replacement id" is an identifier based on which we can decide whether to reuse the element or not during rerendering (e.g. on list change); the value could be anything comparable with `==`
+ *
+ * @param  {string} tagName
+ * @param  {Object} attrs
+ * @param  {...Node} children
+ * @return {HTMLElement}
+ */
+export const t = new Proxy(
+    {},
+    {
+        get(_, prop) {
+            return function () {
+                initMutationObserver();
+
+                return tag.call(undefined, prop, ...arguments);
+            };
+        },
+    },
+);
+
+// -------------------------------------------------------------------
+
+let isMutationObserverInited = false;
+function initMutationObserver() {
+    if (isMutationObserverInited) {
+        return;
+    }
+
+    isMutationObserverInited = true;
+
+    function recursiveObserveCall(method, nodes) {
+        for (let n of nodes) {
+            if (n[method]) {
+                n[method]();
+            }
+            if (n.childNodes) {
+                recursiveObserveCall(method, n.childNodes);
+            }
+        }
+    }
+
+    const observer = new MutationObserver((mutations) => {
+        for (let m of mutations) {
+            recursiveObserveCall("onmount", m.addedNodes);
+            recursiveObserveCall("onunmount", m.removedNodes);
+        }
+    });
+
+    observer.observe(document, { childList: true, subtree: true });
+}
+
+let watchFuncsSym = Symbol();
+let registeredWatchersSym = Symbol();
+let isMountedSym = Symbol();
+let cleanupFuncsSym = Symbol();
+
+function tag(tagName, attrs = {}, ...children) {
+    let el = document.createElement(tagName);
+
+    if (attrs) {
+        for (let attr in attrs) {
+            let val = attrs[attr];
+            let useSetAttr = false;
+
+            if (attr.length > 5 && attr.startsWith("html-")) {
+                useSetAttr = true;
+                attr = attr.substring(5);
+            }
+
+            if (
+                // JS property or regular HTML attribute
+                typeof val != "function" ||
+                // event
+                (attr.length > 2 && attr.startsWith("on"))
+            ) {
+                if (useSetAttr) {
+                    el.setAttribute(attr, val);
+                } else {
+                    el[attr] = val;
+                }
+            } else {
+                el[watchFuncsSym] = el[watchFuncsSym] || [];
+                el[watchFuncsSym].push(() => {
+                    if (!el) {
+                        return;
+                    }
+
+                    if (useSetAttr) {
+                        el.setAttribute(attr, val());
+                    } else {
+                        el[attr] = val();
+                    }
+                });
+            }
+        }
+    }
+
+    let customMount = el.onmount;
+    el.onmount = () => {
+        if (el[isMountedSym]) {
+            return;
+        }
+
+        el[isMountedSym] = true;
+
+        if (el[watchFuncsSym]) {
+            el[registeredWatchersSym] = el[registeredWatchersSym] || [];
+            for (let fn of el[watchFuncsSym]) {
+                el[registeredWatchersSym].push(watch(fn));
+            }
+        }
+
+        customMount?.();
+    };
+
+    let customUnmount = el.onunmount;
+    el.onunmount = () => {
+        if (!el[isMountedSym]) {
+            return;
+        }
+
+        el[isMountedSym] = false;
+
+        if (el[registeredWatchersSym]) {
+            for (let w of el[registeredWatchersSym]) {
+                w.unwatch();
+            }
+        }
+        el[registeredWatchersSym] = null;
+
+        if (el[cleanupFuncsSym]) {
+            for (let cleanup of el[cleanupFuncsSym]) {
+                cleanup();
+            }
+        }
+        el[cleanupFuncsSym] = null;
+
+        customUnmount?.();
+    };
+
+    setChildren(el, children);
+
+    return el;
+}
+
+function setChildren(el, children) {
+    children = toArray(children);
+
+    for (let childOrFunc of children) {
+        if (Array.isArray(childOrFunc)) {
+            // nested array
+            setChildren(el, childOrFunc);
+        } else if (typeof childOrFunc == "function") {
+            initChildrenFuncWatcher(el, childOrFunc);
+        } else {
+            // plain elem
+            el.appendChild(normalizeNode(childOrFunc));
+        }
+    }
+}
+
+function initChildrenFuncWatcher(el, childrenFunc) {
+    let endPlaceholder = document.createComment("");
+    el.appendChild(endPlaceholder);
+
+    let oldChildren = [];
+    let oldKeysMap = new Map();
+
+    let elMoveBefore = el.moveBefore || el.insertBefore;
+
+    el[cleanupFuncsSym] = el[cleanupFuncsSym] || [];
+    el[cleanupFuncsSym].push(() => {
+        oldChildren = null;
+        oldKeysMap = null;
+        endPlaceholder = null;
+    });
+
+    el[watchFuncsSym] = el[watchFuncsSym] || [];
+    el[watchFuncsSym].push(() => {
+        if (!el) {
+            return;
+        }
+
+        let newChildren = toArray(childrenFunc());
+        let totalNewLength = newChildren.length;
+        let newKeysMap = new Map();
+
+        // no previous children
+        if (!oldChildren?.length) {
+            let fragment = document.createDocumentFragment();
+            for (let i = 0; i < totalNewLength; i++) {
+                newChildren[i] = normalizeNode(newChildren[i]);
+
+                fragment.appendChild(newChildren[i]);
+
+                let rid = newChildren[i].rid;
+                if (typeof rid != "undefined") {
+                    if (newKeysMap.has(rid)) {
+                        console.warn("Duplicated rid:", rid, newChildren[i]);
+                    } else {
+                        newKeysMap.set(rid, i);
+                    }
+                }
+            }
+            el.insertBefore(fragment, endPlaceholder);
+            fragment = null;
+
+            oldChildren = newChildren;
+            oldKeysMap = newKeysMap;
+            return;
+        }
+
+        let toMove = [];
+        let toInsert = [];
+        let reused = new Set();
+        let orderedActiveOldIndexes = [];
+
+        // identify new items for reuse or insert
+        for (let newI = 0; newI < totalNewLength; newI++) {
+            newChildren[newI] = normalizeNode(newChildren[newI]);
+
+            let rid = newChildren[newI].rid;
+            if (typeof rid != "undefined") {
+                if (newKeysMap.has(rid)) {
+                    console.warn("Duplicated rid:", rid, newChildren[newI]);
+                } else {
+                    newKeysMap.set(rid, newI);
+                }
+
+                // reuse
+                let oldI = oldKeysMap.get(rid);
+                if (oldI >= 0) {
+                    reused.add(oldChildren[oldI]);
+                    newChildren[newI] = oldChildren[oldI];
+                    orderedActiveOldIndexes.push(oldI);
+                    continue;
+                }
+            }
+
+            toInsert.push({
+                child: newChildren[newI],
+                prev: newChildren[newI - 1],
+            });
+        }
+
+        // since the "reused" children could be in different order from the original ones,
+        // try to find the longest subsequence that is in the correct order
+        // so that we can minimize the required DOM move operations,
+        // aka. only the elements not found in the resulting subsequence must be reordered
+        let okSubsequence = getLongestSubsequence(orderedActiveOldIndexes);
+        if (orderedActiveOldIndexes.length != okSubsequence.length) {
+            orderedActiveOldIndexes.forEach((idx, i) => {
+                if (!okSubsequence.has(idx)) {
+                    toMove.push({
+                        child: oldChildren[idx],
+                        currentPos: idx,
+                        targetPos: i,
+                    });
+                }
+            });
+        }
+
+        // reorder old children
+        for (let m of toMove) {
+            let before = oldChildren[m.targetPos];
+            arrayMove(oldChildren, m.currentPos, m.targetPos);
+            elMoveBefore.call(el, m.child, before);
+        }
+
+        // insert new children
+        for (let ins of toInsert) {
+            if (ins.prev) {
+                ins.prev.after(ins.child);
+            } else {
+                (oldChildren[0] || endPlaceholder).before(ins.child);
+            }
+        }
+
+        // remove missing old children
+        for (let i = 0; i < oldChildren.length; i++) {
+            if (!reused.has(oldChildren[i])) {
+                oldChildren[i].remove?.();
+            }
+        }
+
+        oldChildren = newChildren;
+        oldKeysMap = newKeysMap;
+
+        // clear to make sure no lingering references remain
+        newChildren = null;
+        newKeysMap = null;
+        reused = null;
+        toMove = null;
+        toInsert = null;
+    });
+}
+
+// Returns the elements of the Longest Increasing Subsequence (LIS) for an array of indexes.
+//
+// Note that the returned sequence is in reverse order but for our case
+// it doesn't matter because we are interested only in the elements.
+//
+// For more details and visual representation of the the algorithm, please check:
+// https://en.wikipedia.org/wiki/Longest_increasing_subsequence#Efficient_algorithms
+function getLongestSubsequence(arr) {
+    let ends = [];
+    let predecessors = [];
+
+    for (let i = 0; i < arr.length; i++) {
+        let current = arr[i];
+
+        let low = 0;
+        let mid = 0;
+        let high = ends.length;
+        while (low < high) {
+            mid = Math.floor((low + high) / 2);
+            if (arr[ends[mid]] >= current) {
+                high = mid;
+            } else {
+                low = mid + 1;
+            }
+        }
+
+        if (low > 0) {
+            predecessors[i] = ends[low - 1];
+        }
+
+        ends[low] = i;
+    }
+
+    let result = new Set();
+
+    // reconstruct the LIS elements via backtracking
+    let lastIdx = ends[ends.length - 1];
+    while (typeof lastIdx != "undefined") {
+        result.add(arr[lastIdx]);
+        lastIdx = predecessors[lastIdx];
+    }
+
+    return result;
+}
+
+function arrayMove(arr, from, to) {
+    if (from == to) {
+        return arr;
+    }
+
+    let dir = from > to ? -1 : 1;
+    let target = arr[from];
+
+    for (let i = from; i != to; i += dir) {
+        arr[i] = arr[i + dir];
+    }
+
+    arr[to] = target;
+}
+
+function toArray(val) {
+    if (typeof val == "undefined" || val === null) {
+        return [];
+    }
+
+    return Array.isArray(val) ? val : [val];
+}
+
+function normalizeNode(child) {
+    // wrap as TextNode so that it can be "tracked" and used with appendChild or other similar methods
+    if (typeof child == "string" || typeof child == "number") {
+        let childNode = document.createTextNode(child);
+        childNode.rid = child;
+        return childNode;
+    }
+
+    return child;
+}