shablon 0.0.1-rc.1 → 0.0.1-rc.3

package/README.md

@@ -10,7 +10,7 @@ Shablon - No-build JavaScript frontend framework
 
 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)`
+- State: `store(obj)` and `watch(trackedFunc, optUntrackedFunc)`
 - Template: `t.[tag](attrs, ...children)`
 - Router: `router(routes, options)`
 
@@ -112,10 +112,8 @@ You can find the bundle file at [`dist/shablon.iife.js`](https://github.com/gani
 
 #### 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). -->
+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
@@ -127,7 +125,7 @@ importing it from [npm](https://www.npmjs.com/package/shablon). -->
         ...
     </script>
     ```
-<!--
+
 - npm (`npm -i shablon`):
     ```js
     import { t, store, watch, router } from "shablon"
@@ -135,7 +133,7 @@ importing it from [npm](https://www.npmjs.com/package/shablon). -->
     const data = store({ count: 0 })
     ...
     ```
- -->
+
 ## API
 <details>
 <summary><strong id="api.store">store(obj)</strong></summary>
@@ -168,12 +166,16 @@ data.activity = "rest"
 
 
 <details>
-<summary><strong id="api.watch">watch(callback)</strong></summary>
+<summary><strong id="api.watch">watch(trackedFunc, optUntrackedFunc)</strong></summary>
 
-Watch registers a callback function that fires once on initialization and
-every time any of its `store` reactive dependencies change.
+Watch registers a callback function that fires on initialization and
+every time any of its evaluated `store` reactive properties change.
 
-It returns a "watcher" object that could be used to `unwatch` the registered listener.
+It returns a "watcher" object that could be used to `unwatch()` the registered listener.
+
+_Optionally also accepts a second callback function that is excluded from the evaluated
+store props tracking and instead is invoked only when `trackedFunc` is called
+(could be used as a "track-only" watch pattern)._
 
 For example:
 
@@ -189,7 +191,31 @@ 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.
+"Track-only" pattern example:
+
+```js
+const data = store({
+    a: 0,
+    b: 0,
+    c: 0,
+})
+
+// watch only "a" and "b" props
+watch(() => [
+   data.a,
+   data.b,
+], () => {
+    console.log(data.a)
+    console.log(data.b)
+    console.log(data.c)
+})
+
+data.a++ // trigger watch update
+data.b++ // trigger watch update
+data.c++ // doesn't trigger watch update
+```
+
+Note that for reactive getters, initially the watch trackCallback will be invoked twice because we register a second internal watcher to cache the getter value.
 
 </details>
 
@@ -220,8 +246,8 @@ When a reactive function is set as attribute value or child, it is invoked only
 
 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
+- `onmount: func(el)` - optional callback called when the element is inserted in the DOM
+- `onunmount: func(el)` - 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>

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.0.1-rc.1",
+    "version": "0.0.1-rc.3",
     "name": "shablon",
     "description": "No-build JavaScript framework for Single-page applications",
     "author": "Gani Georgiev",
@@ -24,7 +24,7 @@
     "devDependencies": {
         "jsdom": "^26.0.0",
         "prettier": "^3.6.2",
-        "rolldown": "^1.0.0-beta.44"
+        "rolldown": "^1.0.0-beta.50"
     },
     "prettier": {
         "tabWidth": 4,

package/src/router.js

@@ -43,12 +43,16 @@ export function router(routes, options = { fallbackPath: "#/", transition: true
     let prevDestroy;
 
     let onHashChange = () => {
-        let path = window.location.hash || options.fallbackPath;
+        let path = window.location.hash;
 
-        let route =
-            findActiveRoute(defs, path) || findActiveRoute(defs, options.fallbackPath);
+        let route = findActiveRoute(defs, path);
         if (!route) {
-            console.warn("no route found");
+            if (options.fallbackPath != path) {
+                window.location.hash = options.fallbackPath;
+                return
+            }
+
+            console.warn("missing route:", path);
             return;
         }
 
@@ -57,7 +61,7 @@ export function router(routes, options = { fallbackPath: "#/", transition: true
                 await prevDestroy?.();
                 prevDestroy = await route.handler(route);
             } catch (err) {
-                console.warn("Route navigation failed:", err);
+                console.warn("route navigation failed:", err);
             }
         };
 
@@ -116,7 +120,7 @@ function prepareRoutes(routes) {
                 parts[i].endsWith("}")
             ) {
                 // param
-                parts[i] = "(?<" + parts[i].substring(1, parts[i].length - 1) + ">\\w+)";
+                parts[i] = "(?<" + parts[i].substring(1, parts[i].length - 1) + ">[^\\/#?]+)";
             } else {
                 // regular path segment
                 parts[i] = RegExp.escape(parts[i]);

package/src/state.js

@@ -7,6 +7,7 @@ let cleanTimeoutId;
 
 let idSym = Symbol();
 let parentSym = Symbol();
+let pathsResetedSym = Symbol();
 let childrenSym = Symbol();
 let pathsSubsSym = Symbol();
 let unwatchedSym = Symbol();
@@ -14,11 +15,15 @@ let onRemoveSym = Symbol();
 
 /**
  * Watch registers a callback function that fires on initialization and
- * every time any of its `store` reactive dependencies changes.
+ * every time any of its evaluated `store` reactive properties change.
  *
- * Returns a "watcher" object that could be used to `unwatch()` the registered listener.
+ * It returns a "watcher" object that could be used to `unwatch()` the registered listener.
  *
- * Example:
+ * Optionally also accepts a second callback function that is excluded from the evaluated
+ * store props tracking and instead is invoked only when `trackedFunc` is called
+ * (could be used as a "track-only" watch pattern).
+ *
+ * Simple example:
  *
  * ```js
  * const data = store({ count: 0 })
@@ -32,19 +37,47 @@ let onRemoveSym = Symbol();
  * data.count++ // doesn't trigger watch update
  * ```
  *
- * @param  {Function} callback
+ * "Track-only" example:
+ *
+ * ```js
+ * const data = store({
+ *     a: 0,
+ *     b: 0,
+ *     c: 0,
+ * })
+ *
+ * // watch only "a" and "b" props
+ * watch(() => [
+ *    data.a,
+ *    data.b,
+ * ], () => {
+ *     console.log(data.a)
+ *     console.log(data.b)
+ *     console.log(data.c)
+ * })
+ *
+ * data.a++ // trigger watch update
+ * data.b++ // trigger watch update
+ * data.c++ // doesn't trigger watch update
+ * ```
+ *
+ * @param {Function} trackedFunc
+ * @param {Function} [optUntrackedFunc]
  * @return {{unwatch:Function, last:any, run:Function}}
  */
-export function watch(callback) {
+export function watch(trackedFunc, optUntrackedFunc) {
     let watcher = {
-        [idSym]: "" + Math.random(),
-    };
+        [idSym]: "_" + Math.random(),
+    }
 
     allWatchers.set(watcher[idSym], watcher);
 
     watcher.run = () => {
+        let oldActiveWatcher;
+
         // nested watcher -> register previous watcher as parent
         if (activeWatcher) {
+            oldActiveWatcher = activeWatcher
             watcher[parentSym] = activeWatcher[idSym];
 
             // store immediate children references for quicker cleanup
@@ -53,8 +86,14 @@ export function watch(callback) {
         }
 
         activeWatcher = watcher;
-        watcher.last = callback();
-        activeWatcher = allWatchers.get([watcher[parentSym]]); // restore parent ref (if any)
+        activeWatcher[pathsResetedSym] = false;
+        watcher.last = trackedFunc();
+
+        activeWatcher = null;
+        optUntrackedFunc?.();
+
+        // restore original ref (if any)
+        activeWatcher = oldActiveWatcher;
     };
 
     watcher.unwatch = function () {
@@ -126,7 +165,7 @@ function removeWatcher(id) {
  * 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.
+ * aka. if the final value hasn't changed it will not trigger an unnecessary reactive update.
  *
  * Multiple changes from one or many stores are also automatically batched in a microtask.
  *
@@ -148,6 +187,10 @@ function createProxy(obj, pathWatcherIds) {
 
     let handler = {
         get(obj, prop, target) {
+            if (prop === "__raw") {
+                return obj;
+            }
+
             // getter?
             let getterProp;
             if (descriptors[prop]?.get) {
@@ -184,6 +227,42 @@ function createProxy(obj, pathWatcherIds) {
                 let currentPath = getPath(obj, prop);
                 let activeWatcherId = activeWatcher[idSym];
 
+                activeWatcher[pathsSubsSym] = activeWatcher[pathsSubsSym] || new Set();
+
+                // If this is a rerun of the watcher function, resets any previous
+                // tracking paths because after this new run some of the old
+                // dependencies may no longer be reachable/evaluatable.
+                //
+                // For example, in the below code:
+                //
+                // ```js
+                // const data = store({ a: 0, b: 0, c: 0 })
+                //
+                // watch(() => {
+                //     if (data.a > 0) {
+                //         data.b
+                //     } else {
+                //         data.c
+                //     }
+                // })
+                // ```
+                //
+                // initially ONLY "a" and "c" should be trackable because "b"
+                // is not reachable (aka. its getter is never invoked).
+                //
+                // If we increment `a++`, then in the new run  ONLY "a" and "b" should be trackable
+                // because this time "c" is not reachable (aka. its getter is never invoked)
+                // and its previous tracking should be removed for this watcher.
+                //
+                // Note: The below code works because it reuses the same "subs" reference as in pathWatcherIds
+                //       and this is intentional to avoid unnecessary iterations.
+                if (!activeWatcher[pathsResetedSym]) {
+                    activeWatcher[pathsSubsSym].forEach((subs) => {
+                        subs.delete(activeWatcherId)
+                    })
+                    activeWatcher[pathsResetedSym] = true;
+                }
+
                 let subs = pathWatcherIds.get(currentPath);
                 if (!subs) {
                     subs = new Set();
@@ -191,7 +270,6 @@ function createProxy(obj, pathWatcherIds) {
                 }
                 subs.add(activeWatcherId);
 
-                activeWatcher[pathsSubsSym] = activeWatcher[pathsSubsSym] || new Set();
                 activeWatcher[pathsSubsSym].add(subs);
 
                 // register a child watcher to update the custom getter prop replacement

package/src/template.js

@@ -61,7 +61,7 @@ function initMutationObserver() {
     function recursiveObserveCall(method, nodes) {
         for (let n of nodes) {
             if (n[method]) {
-                n[method]();
+                n[method](n);
             }
             if (n.childNodes) {
                 recursiveObserveCall(method, n.childNodes);
@@ -116,9 +116,9 @@ function tag(tagName, attrs = {}, ...children) {
                     }
 
                     if (useSetAttr) {
-                        el.setAttribute(attr, val());
+                        el.setAttribute(attr, val(el));
                     } else {
-                        el[attr] = val();
+                        el[attr] = val(el);
                     }
                 });
             }
@@ -140,7 +140,7 @@ function tag(tagName, attrs = {}, ...children) {
             }
         }
 
-        customMount?.();
+        customMount?.(el);
     };
 
     let customUnmount = el.onunmount;
@@ -165,7 +165,7 @@ function tag(tagName, attrs = {}, ...children) {
         }
         el[cleanupFuncsSym] = null;
 
-        customUnmount?.();
+        customUnmount?.(el);
     };
 
     setChildren(el, children);
@@ -177,14 +177,17 @@ 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") {
+        if (typeof childOrFunc == "function") {
             initChildrenFuncWatcher(el, childOrFunc);
         } else {
-            // plain elem
-            el.appendChild(normalizeNode(childOrFunc));
+            let normalized = normalizeNode(childOrFunc);
+            if (Array.isArray(normalized)) {
+                // nested array
+                setChildren(el, normalized);
+            } else if (normalized) {
+                // plain elem
+                el.appendChild(normalized);
+            }
         }
     }
 }
@@ -211,7 +214,7 @@ function initChildrenFuncWatcher(el, childrenFunc) {
             return;
         }
 
-        let newChildren = toArray(childrenFunc());
+        let newChildren = toArray(childrenFunc(el));
         let totalNewLength = newChildren.length;
         let newKeysMap = new Map();
 
@@ -395,11 +398,16 @@ function toArray(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") {
+    if (typeof child == "string" || typeof child == "number" || typeof child == "boolean") {
         let childNode = document.createTextNode(child);
         childNode.rid = child;
         return childNode;
     }
 
+    // in case child is DOM Proxy element/array loaded from a store object
+    if (typeof child?.__raw != "undefined") {
+        return child.__raw
+    }
+
     return child;
 }