ks-fwork 2.0.1 → 3.0.1

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "ks-fwork",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "description": "Demo Frontend Framework",
   "license": "ISC",
   "author": "",
   "type": "module",
-  "main": "src/index.js",
-  "exports": "./src/index.js",
+  "main": "dist/ks-fwork.js",
+  "module": "dist/ks-fwork.js",
+  "exports": "./dist/ks-fwork.js",
   "files": [
     "src"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "rollup -c"
+  },
+  "dependencies": {
+    "fast-deep-equal": "^3.1.3"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "rollup": "^4.24.0",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-filesize": "^10.0.0"
   }
 }

package/src/app.js

@@ -2,8 +2,9 @@ import { destroyDOM } from "./destroy-dom.js";
 import { Dispatcher } from "./dispatcher.js";
 import { mountDOM } from "./mount-dom.js";
 import { patchDOM } from "./patch-dom.js";
+import { h } from "./h.js";
 
-export function createApp({state, view, reducers = {} }) {
+export function createApp(RootComponent, props = {}) {
     let parentEl = null;
     let rootNode = null;
     let isMounted = false;
@@ -11,25 +12,10 @@ export function createApp({state, view, reducers = {} }) {
     const dispatcher = new Dispatcher();
     const unsubscribers = [dispatcher.afterEveryCommand(renderApp)];
 
-    // Wire each reducer to its action: when the action is emitted, replace state with the reducer's result.
-    for (const actionName in reducers) {
-        const reducer = reducers[actionName];
-
-        const unsubscribe = dispatcher.subscribe(actionName, (payload) => {
-            state = reducer(state, payload);
-        })
-        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() {
-        const newRootNode = view(state, emit);
-
-        rootNode = patchDOM(rootNode, newRootNode, parentEl);
+    function reset() {
+        parentEl = null;
+        rootNode = null;
+        isMounted = false;
     }
 
     return {
@@ -38,19 +24,18 @@ export function createApp({state, view, reducers = {} }) {
             if (isMounted) throw new Error('The application is already mounted');
 
             parentEl = _parentEl;
-            rootNode = view(state, emit);
+            rootNode = h(RootComponent, props);
             mountDOM(rootNode, parentEl);
+
+            isMounted = true;
         },
 
         // Detach the app: remove its DOM and cancel every subscription.
         unmount() {
-            if (rootNode) {
-                destroyDOM(rootNode);
-            }
-            rootNode = null;
-            unsubscribers.forEach((unsubscribe) => unsubscribe());
+            if (!isMounted) throw new Error('The application is not mounted');
 
-            isMounted = false;
+            destroyDOM(rootNode);
+            reset();
         },
     }
 }

package/src/component.js

@@ -0,0 +1,149 @@
+import { mountDOM } from "./mount-dom.js";
+import { destroyDOM } from "./destroy-dom.js";
+import { patchDOM } from "./patch-dom.js";
+import { DOM_TYPES, extractChildren } from "./h.js";
+import { hasOwnProperty } from "./utils/objects.js";
+
+import equal from 'fast-deep-equal';
+import { Dispatcher } from "./dispatcher.js";
+
+export function defineComponent({ render, state, ...methods }) {
+    class Component {
+        #isMounted = false;
+        #vNode = null;
+        #hostEl = null;
+        #eventHandlers = null;
+        #parentComponent = null;
+        #dispatcher = new Dispatcher();
+        #subscriptions = [];
+
+        constructor(props = {}, eventHandlers = {}, parentComponent = null) {
+            this.props = props;
+            this.state = state ? state(props) : {};
+            this.#eventHandlers = eventHandlers;
+            this.#parentComponent = parentComponent;
+        }
+
+        get elements() {
+            // If vNode is null, return an empty array
+            if (this.#vNode == null) {
+                return [];
+            }
+
+            // If vNode's top element is fragment, return the elements inside it
+            if (this.#vNode.type === DOM_TYPES.FRAGMENT) {
+                return extractChildren(this.#vNode).flatMap((child) => {
+                    if (child.type === DOM_TYPES.COMPONENT) {
+                        return child.component.elements;
+                    }
+
+                    return [child.el];
+                });
+            }
+
+            // If vNode's top element is a single node, return its element
+            return [this.#vNode.el];
+        }
+
+        // Return component's first element
+        get firstElement() {
+            return this.elements[0];
+        }
+
+        // Return component's first element offset inside the parent element. If is not fragment, return offset 0
+        get offset() {
+            if(this.#vNode.type === DOM_TYPES.FRAGMENT) {
+                return Array.from(this.#hostEl.children).indexOf(this.firstElement);
+            }
+
+            return 0;
+        }
+
+        updateProps(props) {
+            const newProps = { ...this.props, ...props };
+
+            if (equal(this.props, newProps)) {
+                return;
+            }
+
+            this.props = newProps;
+            this.#patch();
+        }
+
+        updateState(state) {
+            this.state = { ...this.state, ...state };
+            this.#patch();
+        }
+
+        render() {
+            return render.call(this);
+        }
+
+        emit(eventName, payload) {
+            this.#dispatcher.dispatch(eventName, payload);
+        }
+
+        mount(hostEl, index = null) {
+            if (this.#isMounted) {
+                throw new Error('Component is already mounted');
+            }
+
+            this.#vNode = this.render();
+            mountDOM(this.#vNode, hostEl, index, this);
+            this.#wireEventHandlers();
+
+            this.#hostEl = hostEl;
+            this.#isMounted = true;
+        }
+
+        unmount() {
+            if (!this.#isMounted) {
+                throw new Error('Component is not mounted');
+            }
+
+            destroyDOM(this.#vNode);
+            this.#subscriptions.forEach((unsubscribe) => unsubscribe());
+
+            this.#vNode = null;
+            this.#hostEl = null;
+            this.#isMounted = false;
+            this.#subscriptions = [];
+        }
+
+        #patch() {
+            if (!this.#isMounted) {
+                throw new Error('Component is not mounted');
+            }
+
+            const vNode = this.render();
+            this.#vNode = patchDOM(this.#vNode, vNode, this.#hostEl, this);
+        }
+
+        #wireEventHandlers() {
+            this.#subscriptions = Object.entries(this.#eventHandlers).map(
+                ([eventName, handler]) =>
+                    this.#wireEventHandler(eventName, handler)
+            )
+        }
+
+        #wireEventHandler(eventName, handler) {
+            return this.#dispatcher.subscribe(eventName, (payload) => {
+                if (this.#parentComponent) {
+                    handler.call(this.#parentComponent, payload)
+                } else {
+                    handler(payload)
+                }
+            })
+        }
+    }
+
+    for (const methodName in methods) {
+        if (hasOwnProperty(Component, methodName)) {
+            throw new Error(`Method "${methodName}()" already exists in the component.`);
+        }
+
+        Component.prototype[methodName] = methods[methodName];
+    }
+
+    return Component;
+}

package/src/destroy-dom.js

@@ -21,6 +21,11 @@ export function destroyDOM(vNode) {
             break;
         }
 
+        case DOM_TYPES.COMPONENT: {
+            vNode.component.unmount();
+            break;
+        }
+
         default: {
             throw new Error(`Can't destroy virtual node of type: ${vNode.type}`);
         }

package/src/events.js

@@ -1,20 +1,25 @@
-// 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) {
+export function addEventListeners(listeners = {}, el, hostComponent = null) {
     const addedListeners = {};
 
     Object.entries(listeners).forEach(([eventName, handler]) => {
-        addedListeners[eventName] = addEventListener(eventName, handler, el);
+        addedListeners[eventName] = addEventListener(eventName, handler, el, hostComponent);
     });
 
     return addedListeners;
 }
 
+// Add an event listener to an element
+export function addEventListener(eventName, handler, el, hostComponent = null) {
+    function boundHandler() {
+        hostComponent ? handler.apply(hostComponent, arguments) : handler(...arguments);
+    }
+
+    el.addEventListener(eventName, boundHandler);
+
+    return boundHandler;
+}
+
 // Remove an object of event listeners from an element
 export function removeEventListeners(listeners = {}, el) {
     Object.entries(listeners).forEach(([eventName, handler]) => {

package/src/h.js

@@ -3,16 +3,19 @@ import { withoutNulls } from './utils/arrays.js';
 export const DOM_TYPES = {
     TEXT: 'text',
     ELEMENT: 'element',
-    FRAGMENT: 'fragment'
+    FRAGMENT: 'fragment',
+    COMPONENT: 'component'
 }
 
 // Create a virtual DOM element
 export function h(tag, props = {}, children = []) {
+    const type = typeof tag === 'string' ? DOM_TYPES.ELEMENT : DOM_TYPES.COMPONENT;
+
     return {
         tag,
         props,
+        type,
         children: mapTextNodes(withoutNulls(children)),
-        type: DOM_TYPES.ELEMENT,
     }
 }
 
@@ -53,6 +56,7 @@ export function lipsum(numberOfParagraphs) {
     );
 }
 
+// Recursively extract a node's children into a flat list, dissolving any nested fragments into their child nodes
 export function extractChildren(vNode) {
     if (vNode.children == null) return [];
 

package/src/index.js

@@ -1,2 +1,3 @@
 export { createApp } from './app.js'
+export { defineComponent } from './component.js'
 export { h, hFragment, hString } from './h.js'

package/src/mount-dom.js

@@ -1,9 +1,10 @@
 import { DOM_TYPES } from "./h.js";
 import { setAttributes } from './attributes.js'
 import { addEventListeners } from "./events.js";
+import { extractPropsAndEvents } from "./utils/props.js";
 
 // Recursively mount a virtual node (and its subtree) into a real parent DOM element.
-export function mountDOM(vNode, parentEl, index) {
+export function mountDOM(vNode, parentEl, index, hostComponent = null) {
     switch (vNode.type) {
         case DOM_TYPES.TEXT: {
             createTextNode(vNode, parentEl, index);
@@ -11,15 +12,19 @@ export function mountDOM(vNode, parentEl, index) {
         }
 
         case DOM_TYPES.ELEMENT: {
-            createElementNode(vNode, parentEl, index);
+            createElementNode(vNode, parentEl, index, hostComponent);
             break;
         }
 
         case DOM_TYPES.FRAGMENT: {
-            createFragmentNode(vNode, parentEl, index);
+            createFragmentNode(vNode, parentEl, index, hostComponent);
             break;
         }
 
+        case DOM_TYPES.COMPONENT: {
+            createComponentNode(vNode, parentEl, index, hostComponent);
+        }
+
         default: {
             throw new Error(`Can't mount virtual node of type: ${vNode.type}`);
         }
@@ -36,38 +41,49 @@ function createTextNode(vNode, parentEl, index) {
     insert(textNode, parentEl, index);
 }
 
-// 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, index) {
-    const { tag, props, children } = vNode;
+// 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, index, hostComponent) {
+    const { tag, children } = vNode;
 
     const el = document.createElement(tag);
-    addProps(el, props, vNode);
+    addProps(el, vNode, hostComponent);
     vNode.el = el;
 
-    children.forEach((child) => mountDOM(child, el));
+    children.forEach((child) => mountDOM(child, el, null, hostComponent));
     insert(el, parentEl, index);
 }
 
 // Fragment has no DOM element. Mount its children directly into the parent.
-function createFragmentNode(vNode, parentEl, index) {
+function createFragmentNode(vNode, parentEl, index, hostComponent) {
     const { children } = vNode;
     vNode.el = parentEl;
 
     children.forEach((child, i) => {
-        mountDOM(child, parentEl, index ? index + i : null)
+        mountDOM(child, parentEl, index ? index + i : null, hostComponent)
     });
 }
 
+function createComponentNode(vNode, parentEl, index, hostComponent) {
+    const Component = vNode.tag;
+    const { props, events } = extractPropsAndEvents(vNode);
+    const component = new Component(props, events, hostComponent);
+
+    component.mount(parentEl, index);
+    vNode.component = component;
+    vNode.el = component.firstElement;
+}
+
 // Split props into event listeners ('on') and attributes and add them to DOM element.
-function addProps(el, props, vNode) {
-    const { on: events, ...attrs} = props;
+function addProps(el, vNode, hostComponent) {
+    const { props: attrs, events} = extractPropsAndEvents(vNode);
 
-    vNode.listeners = addEventListeners(events, el);
+    vNode.listeners = addEventListeners(events, el, hostComponent);
     setAttributes(el, attrs);
 }
 
+// Insert element into parent element at the specified index (or append if no index given)
 function insert(el, parentEl, index) {
+    // Append if no index specified (null or undefined)
     if (index == null) {
         parentEl.append(el);
         return;
@@ -80,8 +96,10 @@ function insert(el, parentEl, index) {
     const children = parentEl.childNodes;
 
     if (index >= children.length) {
+        // Append if index is greater than or equal to the parent element's length of children
         parentEl.append(el);
     } else {
+        // Insert before the element at the specified index
         parentEl.insertBefore(el, children[index]);
     }
 }

package/src/nodes-equal.js

@@ -1,11 +1,23 @@
 import { DOM_TYPES } from "./h.js";
 
 export function areNodesEqual(nodeOne, nodeTwo) {
+    // Nodes are different type
     if (nodeOne.type !== nodeTwo.type) return false;
 
     if (nodeOne.type === DOM_TYPES.ELEMENT) {
-        return nodeOne.tag === nodeTwo.tag;
+        const { tag: tagOne, props: { key: keyOne } } = nodeOne;
+        const { tag: tagTwo, props: { key: keyTwo } } = nodeTwo;
+
+        return tagOne === tagTwo && keyOne === keyTwo;
+    }
+
+    if (nodeOne.type === DOM_TYPES.COMPONENT) {
+        const { tag: componentOne, props: { key: keyOne } } = nodeOne;
+        const { tag: componentTwo, props: { key: keyTwo } } = nodeTwo;
+
+        return componentOne === componentTwo && keyOne === keyTwo;
     }
 
+    // Text and fragment nodes are always equal
     return true;
 }

package/src/patch-dom.js

@@ -7,16 +7,24 @@ import { removeAttribute, removeStyle, setAttribute, setStyle } from "./attribut
 import { ARRAY_DIFF_OP, arraysDiff, arraysDiffSequence } from "./utils/arrays.js";
 import { isNotBlankOrEmptyString } from "./utils/strings.js";
 import { addEventListener } from "./events.js";
+import { extractPropsAndEvents } from "./utils/props.js";
 
-export function patchDOM(oldVNode, newVNode, parentEl) {
+export function patchDOM(oldVNode, newVNode, parentEl, hostComponent = null) {
+    // Nodes are too different to reuse/patch.
     if (!areNodesEqual(oldVNode, newVNode)) {
+        // Remember where the old node was located inside the parent so the replacement lands in the same spot.
         const index = findIndexInParent(parentEl, oldVNode.el);
+
+        // Destroy the old node and its whole subtree.
         destroyDOM(oldVNode);
-        mountDOM(newVNode, parentEl, index);
+
+        // Mount the new node and its whole subtree at the index of the old node.
+        mountDOM(newVNode, parentEl, index, hostComponent);
 
         return newVNode;
     }
 
+    // Copy over the DOM element reference
     newVNode.el = oldVNode.el;
 
     switch (newVNode.type) {
@@ -26,16 +34,22 @@ export function patchDOM(oldVNode, newVNode, parentEl) {
         }
 
         case DOM_TYPES.ELEMENT: {
-            patchElement(oldVNode, newVNode);
+            patchElement(oldVNode, newVNode, hostComponent);
+            break;
+        }
+
+        case DOM_TYPES.COMPONENT: {
+            patchComponent(oldVNode, newVNode);
             break;
         }
     }
 
-    patchChildren(oldVNode, newVNode);
+    patchChildren(oldVNode, newVNode, hostComponent);
 
     return newVNode;
 }
 
+// Get index of the element inside the parent element
 function findIndexInParent(parentEl, el) {
     const index = Array.from(parentEl.childNodes).indexOf(el);
     if (index < 0) return null;
@@ -53,7 +67,7 @@ function patchText(oldVNode, newVNode) {
     }
 }
 
-function patchElement(oldVNode, newVNode) {
+function patchElement(oldVNode, newVNode, hostComponent) {
     const el = oldVNode.el;
 
     const {
@@ -75,7 +89,17 @@ function patchElement(oldVNode, newVNode) {
     patchAttrs(el, oldAttrs, newAttrs);
     patchClasses(el, oldClass, newClass);
     patchStyles(el, oldStyle, newStyle);
-    newVNode.listeners = patchEvents(el, oldListeners, oldEvents, newEvents);
+    newVNode.listeners = patchEvents(el, oldListeners, oldEvents, newEvents, hostComponent);
+}
+
+function patchComponent(oldVNode, newVNode) {
+    const { component } = oldVNode;
+    const { props } = extractPropsAndEvents(newVNode);
+
+    component.updateProps(props);
+
+    newVNode.component = component;
+    newVNode.el = component.firstElement;
 }
 
 function patchAttrs(el, oldAttrs, newAttrs) {
@@ -124,7 +148,7 @@ function patchStyles(el, oldStyle = {}, newStyle = {}) {
     }
 }
 
-function patchEvents(el, oldListeners = {}, oldEvents = {}, newEvents = {}) {
+function patchEvents(el, oldListeners = {}, oldEvents = {}, newEvents = {}, hostComponent) {
     const { removed, added, updated}  = objectsDiff(oldEvents, newEvents);
 
     for (const eventName of removed.concat(updated)) {
@@ -134,46 +158,55 @@ function patchEvents(el, oldListeners = {}, oldEvents = {}, newEvents = {}) {
     const addedListeners = {};
 
     for (const eventName of added.concat(updated)) {
-        addedListeners[eventName] = addEventListener(eventName, newEvents[eventName], el);
+        addedListeners[eventName] = addEventListener(eventName, newEvents[eventName], el, hostComponent);
     }
 
     return addedListeners;
 }
 
-function patchChildren(oldVNode, newVNode) {
+// Reconcile a node's child lists.
+function patchChildren(oldVNode, newVNode, hostComponent) {
     const oldChildren = extractChildren(oldVNode);
     const newChildren = extractChildren(newVNode);
     const parentEl = oldVNode.el;
 
+    // Create the sequence of operations to match the note's child lists.
     const diffSeq = arraysDiffSequence(oldChildren, newChildren, areNodesEqual);
 
+    // Loop over the operations and perform the operations on the DOM.
     for (const operation of diffSeq) {
         const { originalIndex, from, index, item } = operation;
+        // Get the host component’s offset, if there is one; offset is 0 otherwise
+        const offset = hostComponent?.offset ?? 0;
 
         switch (operation.op) {
+            // New node with no old counterpart: build its subtree and insert it at `index`
             case ARRAY_DIFF_OP.ADD: {
-                mountDOM(item, parentEl, index)
+                mountDOM(item, parentEl, index, hostComponent)
                 break;
             }
 
+            // Old node gone from the new list: destroy it and its subtree
             case ARRAY_DIFF_OP.REMOVE: {
                 destroyDOM(item);
                 break;
             }
 
+            // Node still present but at a different position: move the existing node to its new spot, then patch it in place for any inner changes
             case ARRAY_DIFF_OP.MOVE: {
                 const el = oldChildren[from].el;
-                const elAtTargetIndex = parentEl.childNodes[index];
-
+                const elAtTargetIndex = parentEl.childNodes[index + offset];
                 parentEl.insertBefore(el, elAtTargetIndex);
-                patchDOM(oldChildren[from], newChildren[index], parentEl);
+
+                patchDOM(oldChildren[from], newChildren[index], parentEl, hostComponent);
                 break;
             }
 
+            // Same node, same position, but its contents may still differ, so recurse
             case ARRAY_DIFF_OP.NOOP: {
-                patchDOM(oldChildren[originalIndex], newChildren[index], parentEl)
+                patchDOM(oldChildren[originalIndex], newChildren[index], parentEl, hostComponent);
                 break;
             }
         }
     }
-}
+}