ks-fwork 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ks-fwork",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Demo Frontend Framework",
   "license": "ISC",
   "author": "",

package/src/app.js

@@ -4,43 +4,49 @@ import { mountDOM} from "./mount-dom.js";
 
 export function createApp({state, view, reducers = {} }) {
     let parentEl = null;
-    let vdom = null;
+    let rootNode = null;
 
     const dispatcher = new Dispatcher();
-    const subscriptions = [dispatcher.afterEveryCommand(renderApp)];
-
-    function emit(eventName, payload) {
-        dispatcher.dispatch(eventName, payload);
-    }
+    const unsubscribers = [dispatcher.afterEveryCommand(renderApp)];
 
+    // Wire each reducer to its action: when the action fires, replace state with the reducer's result.
     for (const actionName in reducers) {
         const reducer = reducers[actionName];
 
-        const subs = dispatcher.subscribe(actionName, (payload) => {
+        const unsubscribe = dispatcher.subscribe(actionName, (payload) => {
             state = reducer(state, payload);
         })
-        subscriptions.push(subs);
+        unsubscribers.push(unsubscribe);
+    }
+
+    // Passed into the view so it can trigger actions without touching the dispatcher directly.
+    function emit(actionName, payload) {
+        dispatcher.dispatch(actionName, payload);
     }
 
     function renderApp() {
-        if (vdom) {
-            destroyDOM(vdom);
+        if (rootNode) {
+            destroyDOM(rootNode);
         }
 
-        vdom = view(state, emit);
-        mountDOM(vdom, parentEl);
+        rootNode = view(state, emit);
+        mountDOM(rootNode, parentEl);
     }
 
     return {
+        // Attach the app to a real DOM element and do the first render.
         mount(_parentEl) {
             parentEl = _parentEl;
             renderApp();
         },
 
+        // Detach the app: remove its DOM and cancel every subscription.
         unmount() {
-            destroyDOM(vdom);
-            vdom = null;
-            subscriptions.forEach((unsubscribe) => unsubscribe());
+            if (rootNode) {
+                destroyDOM(rootNode);
+            }
+            rootNode = null;
+            unsubscribers.forEach((unsubscribe) => unsubscribe());
         },
     }
 }

package/src/attributes.js

@@ -1,3 +1,4 @@
+// Set attributes to an element
 export function setAttributes(el, attrs) {
     const { class: className, style, ...otherAttrs } = attrs;
 
@@ -16,6 +17,7 @@ export function setAttributes(el, attrs) {
     }
 }
 
+// Set class or array of classes to an element
 function setClass(el, className) {
     el.className = '';
 
@@ -30,17 +32,22 @@ function setClass(el, className) {
     }
 }
 
+// Set style to an element
 export function setStyle(el, name, value) {
     el.style[name] = value;
 }
 
+// Remove style from an element
 export function removeStyle(el, name) {
     el.style[name] = null;
 }
 
+// Set attribute to an element
 export function setAttribute(el, name, value) {
+    // Remove attributes with no values
     if (value == null) {
         removeAttribute(el, name);
+    // Set 'data-*' attributes separately
     } else if (name.startsWith('data-')) {
         el.setAttribute(name, value);
     } else {
@@ -48,6 +55,7 @@ export function setAttribute(el, name, value) {
     }
 }
 
+// Remove attribute from an element
 export function removeAttribute(el, name) {
     el[name] = null;
     el.removeAttribute(name);

package/src/destroy-dom.js

@@ -1,52 +1,57 @@
 import { removeEventListeners } from './events.js'
 import { DOM_TYPES } from "./h.js";
 
-
-export function destroyDOM(vdom) {
-    const { type } = vdom;
+// Recursively destroy a virtual node (and its subtree).
+export function destroyDOM(vNode) {
+    const { type } = vNode;
 
     switch (type) {
         case DOM_TYPES.TEXT: {
-            removeTextNode(vdom);
+            removeTextNode(vNode);
             break;
         }
 
         case DOM_TYPES.ELEMENT: {
-            removeElementNode(vdom);
+            removeElementNode(vNode);
             break;
         }
 
         case DOM_TYPES.FRAGMENT: {
-            removeFragmentNode(vdom);
+            removeFragmentNode(vNode);
             break;
         }
 
         default: {
-            throw new Error(`Can't destroy DOM of type: ${vdom.type}`);
+            throw new Error(`Can't destroy virtual node of type: ${vNode.type}`);
         }
     }
 
-    delete vdom.el;
+    // Drop the reference to the DOM element
+    delete vNode.el;
 }
 
-function removeTextNode(vdom) {
-    const { el } = vdom;
+// Detach the text node from the DOM.
+function removeTextNode(vNode) {
+    const { el } = vNode;
     el.remove();
 }
 
-function removeElementNode(vdom) {
-    const { el, children, listeners } = vdom;
+// Recursively destroy the element's children, remove its event listeners, then detach the element.
+function removeElementNode(vNode) {
+    const { el, children, listeners } = vNode;
 
-    el.remove();
     children.forEach(destroyDOM)
 
     if (listeners) {
         removeEventListeners(listeners, el);
-        delete vdom.listeners;
+        delete vNode.listeners;
     }
+
+    el.remove();
 }
 
-function removeFragmentNode() {
-    const { children } = vdom;
+// Fragment has no DOM element. Destroy fragment node's children recursively.
+function removeFragmentNode(vNode) {
+    const { children } = vNode;
     children.forEach(destroyDOM);
 }

package/src/dispatcher.js

@@ -1,40 +1,56 @@
 export class Dispatcher {
-    #subs = new Map();
+    // All registered commands mapped to their handlers (callback functions)
+    #handlersByCommand = new Map();
+
+    // Handlers that run after every dispatch, regardless of command
     #afterHandlers = [];
 
+    // Subscribe to a command
     subscribe(commandName, handler) {
-        if (!this.#subs.has(commandName)) {
-            this.#subs.set(commandName, []);
+        // Create an empty handler array for this command if none exists yet
+        if (!this.#handlersByCommand.has(commandName)) {
+            this.#handlersByCommand.set(commandName, []);
         }
 
-        const handlers = this.#subs.get(commandName);
+        // Get the handler array for this command
+        const handlers = this.#handlersByCommand.get(commandName);
+
+        // If this exact handler reference is already registered, skip it and return a no-op unsubscribe
         if (handlers.includes(handler)) {
             return () => {}
         }
 
+        // Register the handler
         handlers.push(handler);
 
+        // Return unsubscribe function
         return () => {
-            const idx = handlers.indexOf(handler);
-            handlers.splice(idx, 1);
+            const index = handlers.indexOf(handler);
+            handlers.splice(index, 1);
         }
     }
 
+    // Register a handler that will be called after every dispatch
     afterEveryCommand(handler) {
         this.#afterHandlers.push(handler);
 
+        // Return unsubscribe function
         return () => {
-            const idx = this.#afterHandlers.indexOf(handler);
-            this.#afterHandlers.splice(idx, 1);
+            const index = this.#afterHandlers.indexOf(handler);
+            this.#afterHandlers.splice(index, 1);
         }
     }
 
+    // Dispatch a command: run its handlers with the payload
     dispatch(commandName, payload) {
-        if (this.#subs.has(commandName)) {
-            this.#subs.get(commandName).forEach((handler) => handler(payload))
+        if (this.#handlersByCommand.has(commandName)) {
+            // Call every handler subscribed to this command
+            this.#handlersByCommand.get(commandName).forEach((handler) => handler(payload))
         } else {
             console.warn(`No handlers for command: ${commandName}`);
         }
+
+        // Call all 'afterEveryCommand' handlers (no payload)
         this.#afterHandlers.forEach((handler) => handler());
     }
 }

package/src/events.js

@@ -1,19 +1,21 @@
+// Add an event listener to an element
 export function addEventListener(eventName, handler, el) {
     el.addEventListener(eventName, handler);
     return handler;
 }
 
+// Add an object of event listeners to an element
 export function addEventListeners(listeners = {}, el) {
     const addedListeners = {};
 
     Object.entries(listeners).forEach(([eventName, handler]) => {
-        const listener = addEventListener(eventName, handler, el);
-        addedListeners[eventName] = listener;
+        addedListeners[eventName] = addEventListener(eventName, handler, el);
     });
 
     return addedListeners;
 }
 
+// Remove an object of event listeners from an element
 export function removeEventListeners(listeners = {}, el) {
     Object.entries(listeners).forEach(([eventName, handler]) => {
         el.removeEventListener(eventName, handler);

package/src/h.js

@@ -6,7 +6,7 @@ export const DOM_TYPES = {
     FRAGMENT: 'fragment'
 }
 
-// Create a virtual DOM element.
+// Create a virtual DOM element
 export function h(tag, props = {}, children = []) {
     return {
         tag,
@@ -16,17 +16,15 @@ export function h(tag, props = {}, children = []) {
     }
 }
 
-// Transform strings into text virtual nodes.
-function mapTextNodes(children) {
-    return children.map((child) =>
-        typeof child === 'string' ? hString(child) : child
-    )
-}
-
+// Create a virtual text node
 export function hString(str) {
-    return { type: DOM_TYPES.TEXT, value: str };
+    return {
+        type: DOM_TYPES.TEXT,
+        value: str
+    };
 }
 
+// Create a fragment node
 export function hFragment(vNodes) {
     return {
         children: mapTextNodes(withoutNulls(vNodes)),
@@ -34,6 +32,13 @@ export function hFragment(vNodes) {
     }
 }
 
+// Transform strings into text virtual nodes
+function mapTextNodes(children) {
+    return children.map((child) =>
+        typeof child === 'string' ? hString(child) : child
+    )
+}
+
 // Create an array with specified amount of empty elements and fill them with 'p' virtual node that has text as children.
 export function lipsum(numberOfParagraphs) {
     const text = `Lorem ipsum dolor sit amet, consectetur adipiscing elit,

package/src/mount-dom.js

@@ -2,59 +2,65 @@ import { DOM_TYPES } from "./h.js";
 import { setAttributes } from './attributes.js'
 import { addEventListeners } from "./events.js";
 
-export function mountDOM(vdom, parentEl) {
-    switch (vdom.type) {
+// Recursively mount a virtual node (and its subtree) into a real parent DOM element.
+export function mountDOM(vNode, parentEl) {
+    switch (vNode.type) {
         case DOM_TYPES.TEXT: {
-            createTextNode(vdom, parentEl);
+            createTextNode(vNode, parentEl);
             break;
         }
 
         case DOM_TYPES.ELEMENT: {
-            createElementNode(vdom, parentEl);
+            createElementNode(vNode, parentEl);
             break;
         }
 
         case DOM_TYPES.FRAGMENT: {
-            createFragmentNode(vdom, parentEl);
+            createFragmentNode(vNode, parentEl);
             break;
         }
 
         default: {
-            throw new Error(`Can't mount DOM of type: ${vdom.type}`);
+            throw new Error(`Can't mount virtual node of type: ${vNode.type}`);
         }
     }
+}
 
-    function createTextNode(vdom, parentEl) {
-        const { value } = vdom;
+// Create a real text node, save a reference to it on the vNode, and append it to the parent.
+function createTextNode(vNode, parentEl) {
+    const { value } = vNode;
 
-        const textNode = document.createTextNode(value);
-        vdom.el = textNode;
+    const textNode = document.createTextNode(value);
+    vNode.el = textNode;
 
-        parentEl.append(textNode);
-    }
+    parentEl.append(textNode);
+}
 
-    function createElementNode(vdom, parentEl) {
-        const { tag, props, children } = vdom;
+// Create a real element, apply its props, recursively mount its children into it,
+// then append the finished element to the parent.
+function createElementNode(vNode, parentEl) {
+    const { tag, props, children } = vNode;
 
-        const element = document.createElement(tag);
-        addProps(element, props, vdom);
-        vdom.el = element;
+    const el = document.createElement(tag);
+    addProps(el, props, vNode);
+    vNode.el = el;
 
-        children.forEach((child) => mountDOM(child, element));
-        parentEl.append(element);
-    }
+    children.forEach((child) => mountDOM(child, el));
+    parentEl.append(el);
+}
 
-    function addProps(el, props, vdom) {
-        const { on: events, ...attrs} = props;
+// Fragment has no DOM element. Mount its children directly into the parent.
+function createFragmentNode(vNode, parentEl) {
+    const { children } = vNode;
+    vNode.el = parentEl;
 
-        vdom.listeners = addEventListeners(events, el);
-        setAttributes(el, attrs);
-    }
+    children.forEach((child) => mountDOM(child, parentEl));
+}
 
-    function createFragmentNode(vdom, parentEl) {
-        const { children } = vdom;
-        vdom.el = parentEl;
+// Split props into event listeners ('on') and attributes and add them to DOM element.
+function addProps(el, props, vNode) {
+    const { on: events, ...attrs} = props;
 
-        children.forEach((child) => mountDOM(child, parentEl));
-    }
+    vNode.listeners = addEventListeners(events, el);
+    setAttributes(el, attrs);
 }