rasti 3.0.0 → 4.0.0-alpha.0

package/lib/View.cjs

@@ -2,19 +2,12 @@
 
 var Emitter = require('./Emitter.cjs');
 var utils_getResult = require('./utils/getResult.cjs');
+var utils_validateListener = require('./utils/validateListener.cjs');
 
 /*
  * These option keys will be extended on the view instance.
  */
-const viewOptions = {
-    el : true,
-    tag : true,
-    attributes : true,
-    events : true,
-    model : true,
-    template : true,
-    onDestroy : true
-};
+const viewOptions = ['el', 'tag', 'attributes', 'events', 'model', 'template', 'onDestroy'];
 
 /**
  * - Listens for changes and renders the UI.
@@ -31,14 +24,15 @@ const viewOptions = {
  * @module
  * @extends Emitter
  * @param {object} options Object containing options. The following keys will be merged into the view instance: `el`, `tag`, `attributes`, `events`, `model`, `template`, `onDestroy`.
- * @property {node|function} el Every view has a root DOM element stored at `this.el`. If not present, it will be created. If `this.el` is a function, it will be called to get the element at `this.ensureElement`, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.
- * @property {string|function} tag If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. Default is `div`. If it is a function, it will be called to get the tag, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.
- * @property {object|function} attributes If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. If it is a function, it will be called to get the attributes object, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.
- * @property {object|function} events Object in the format `{'event selector' : 'listener'}`. It will be used to bind delegated event listeners to the root element. If it is a function, it will be called to get the events object, bound to the view instance. See {@link module_view_delegateevents View.delegateEvents}.
+ * @property {node|Function} el Every view has a root DOM element stored at `this.el`. If not present, it will be created. If `this.el` is a function, it will be called to get the element at `this.ensureElement`, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.
+ * @property {string|Function} tag If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. Default is `div`. If it is a function, it will be called to get the tag, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.
+ * @property {object|Function} attributes If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. If it is a function, it will be called to get the attributes object, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.
+ * @property {object|Function} events Object in the format `{'event selector' : 'listener'}`. It will be used to bind delegated event listeners to the root element. If it is a function, it will be called to get the events object, bound to the view instance. See {@link module_view_delegateevents View.delegateEvents}.
  * @property {object} model A model or any object containing data and business logic.
- * @property {function} template A function that returns a string with the view's inner HTML. See {@link module_view__render View.render}. 
+ * @property {Function} template A function that returns a string with the view's inner HTML. See {@link module_view__render View.render}. 
+ * @property {number} uid Unique identifier for the view instance. This can be used to generate unique IDs for elements within the view. It is automatically generated and should not be set manually.
  * @example
- * import { View } from 'rasti';
+ * import { View, Model } from 'rasti';
  * 
  * class Timer extends View {
  *     constructor(options) {
@@ -63,9 +57,6 @@ class View extends Emitter {
         super();
         // Call preinitialize.
         this.preinitialize.apply(this, arguments);
-        // Generate unique id.
-        // Useful to generate element ids.
-        this.uid = `uid${++View.uid}`;
         // Store delegated event listeners,
         // so they can be unbound later.
         this.delegatedEventListeners = [];
@@ -74,17 +65,23 @@ class View extends Emitter {
         this.children = [];
         // Mutable array to store handlers to be called on destroy.
         this.destroyQueue = [];
-        // Extend "this" with options, mapping viewOptions keys.
-        Object.keys(options).forEach(key => {
-            if (viewOptions[key]) this[key] = options[key];
+        this.viewOptions = [];
+        // Extend "this" with options.
+        viewOptions.forEach(key => {
+            if (key in options) {
+                this[key] = options[key];
+                this.viewOptions.push(key);
+            }
         });
+        // Ensure that the view has a unique id at `this.uid`.
+        this.ensureUid();
         // Ensure that the view has a root element at `this.el`.
         this.ensureElement();
     }
 
     /**
      * If you define a preinitialize method, it will be invoked when the view is first created, before any instantiation logic is run.
-     * @param {object} attrs Object containing model attributes to extend `this.attributes`.
+     * @param {object} options The view options.
      */
     preinitialize() {}
 
@@ -119,6 +116,8 @@ class View extends Emitter {
         this.destroyChildren();
         // Undelegate `this.el` event listeners
         this.undelegateEvents();
+        // Stop listening to events.
+        this.stopListening();
         // Unbind `this` events.
         this.off();
         // Call destroy queue.
@@ -126,6 +125,8 @@ class View extends Emitter {
         this.destroyQueue = [];
         // Call onDestroy lifecycle method
         this.onDestroy.apply(this, arguments);
+        // Set destroyed flag.
+        this.destroyed = true;
         // Return `this` for chaining.
         return this;
     }
@@ -157,6 +158,13 @@ class View extends Emitter {
         this.children = [];
     }
 
+    /**
+     * Ensure that the view has a unique id at `this.uid`.
+     */
+    ensureUid() {
+        if (!this.uid) this.uid = `r-${++View.uid}`;
+    }
+
     /**
      * Ensure that the view has a root element at `this.el`.
      * You shouldn't call this method directly. It's called from the constructor.
@@ -223,26 +231,43 @@ class View extends Emitter {
      * All attached listeners are bound to the view, ensuring that `this` refers to the view object when the listeners are invoked.
      * When `delegateEvents` is called again, possibly with a different events object, all previous listeners are removed and delegated afresh.
      * 
-     * The listeners will be invoked with the event and the view as arguments.
-     * 
+     * **Listener signature:** `(event, view, matched)`
+     * - `event`:   The native DOM event object.
+     * - `view`:    The current view instance (`this`).
+     * - `matched`: The element that satisfies the selector. If no selector is provided, it will be the view's root element (`this.el`).
+     *
+     * If more than one ancestor between `event.target` and the view's root element matches the selector, the listener will be
+     * invoked **once for each matched element** (from inner to outer).
+     *
      * @param {object} [events] Object in the format `{'event selector' : 'listener'}`. Used to bind delegated event listeners to the root element.
      * @return {Rasti.View} Returns `this` for chaining.
      * @example
-     * // Using a function.
+     * // Using prototype (recommended for static events)
      * class Modal extends View {
+     *     onClickOk(event, view, matched) {
+     *         // matched === the button.ok element that was clicked
+     *         this.close();
+     *     }
+     *     
+     *     onClickCancel() {
+     *         this.destroy();
+     *     }
+     * }
+     * Modal.prototype.events = {
+     *     'click button.ok': 'onClickOk',
+     *     'click button.cancel': 'onClickCancel',
+     *     'submit form': 'onSubmit'
+     * };
+     * 
+     * // Using a function for dynamic events
+     * class DynamicView extends View {
      *     events() {
      *         return {
-     *             'click button.ok': 'onClickOkButton',
-     *             'click button.cancel': function() {}
+     *             [`click .${this.model.buttonClass}`]: 'onButtonClick',
+     *             'click': 'onRootClick'
      *         };
      *     }
      * }
-     * 
-     * // Using an object.
-     * Modal.prototype.events = {
-     *     'click button.ok' : 'onClickOkButton',
-     *     'click button.cancel' : function() {}
-     * };
      */
     delegateEvents(events) {
         if (!events) events = utils_getResult(this.events, this);
@@ -259,13 +284,10 @@ class View extends Emitter {
             const selector = keyParts.join(' ');
 
             let listener = events[key];
-            // Listener may be a string representing a method name on the view,
-            // or a function.
-            listener = (
-                typeof listener === 'string' ?
-                    this[listener] :
-                    listener
-            ).bind(this);
+            // Listener may be a string representing a method name on the view, or a function.
+            if (typeof listener === 'string') listener = this[listener];
+            // Validate listener is a function.
+            utils_validateListener(listener);
 
             if (!eventTypes[type]) eventTypes[type] = [];
 
@@ -277,7 +299,20 @@ class View extends Emitter {
             const typeListener = (event) => {
                 // Iterate and run every individual listener if the selector matches.
                 eventTypes[type].forEach(({ selector, listener }) => {
-                    if (!selector || event.target.closest(selector)) listener(event, this);
+                    // No selector provided: invoke listener once with root element.
+                    if (!selector) {
+                        listener.call(this, event, this, this.el);
+                        return;
+                    }
+
+                    let node = event.target;
+                    // Traverse ancestors until reaching the view root (`this.el`).
+                    while (node && node !== this.el) {
+                        if (node.matches && node.matches(selector)) {
+                            listener.call(this, event, this, node);
+                        }
+                        node = node.parentElement;
+                    }
                 });
             };
 
@@ -305,17 +340,16 @@ class View extends Emitter {
     }
 
     /**
-     * Renders the view.
+     * Renders the view.  
      * This method should be overridden with custom logic.
      * The only convention is to manipulate the DOM within the scope of `this.el`,
-     * and to return `this` for chaining.
-     * If you add any child views, you should call `this.destroyChildren` before re-rendering.
-     * The default implementation sets the innerHTML of `this.el` with the result
-     * of calling `this.template`, passing `this.model` as an argument.
-     * <br><br> &#9888; **Security Notice:** The default implementation utilizes `innerHTML` on the root element
-     * for rendering, which may introduce Cross-Site Scripting (XSS) risks. Ensure that any user-generated 
-     * content is properly sanitized before inserting it into the DOM. You can use the @link{#module_view_sanitize View.sanitize} 
-     * static method to escape HTML entities in a string.  
+     * and to return `this` for chaining.  
+     * If you add any child views, you should call `this.destroyChildren` before re-rendering.  
+     * The default implementation updates `this.el`'s innerHTML with the result
+     * of calling `this.template`, passing `this.model` as the argument.
+     * <br><br> &#9888; **Security Notice:** The default implementation utilizes `innerHTML`, which may introduce Cross-Site Scripting (XSS) risks.  
+     * Ensure that any user-generated content is properly sanitized before inserting it into the DOM. 
+     * You can use the {@link #module_view_sanitize View.sanitize} static method to escape HTML entities in a string.  
      * For best practices on secure data handling, refer to the 
      * [OWASP's XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html).<br><br>
      * @return {Rasti.View} Returns `this` for chaining.
@@ -332,7 +366,7 @@ class View extends Emitter {
      * Override this method to provide a custom escape function.
      * This method is inherited by {@link #module_component Component} and used to escape template interpolations.
      * @static
-     * @param {string} str String to escape.
+     * @param {string} value String to escape.
      * @return {string} Escaped string.
      */
     static sanitize(value) {
@@ -346,8 +380,16 @@ class View extends Emitter {
     }
 }
 
-/*
- * Unique Id
+/**
+ * Counter for generating unique IDs for view instances.  
+ * This is primarily used to assign unique identifiers to each view instance (`this.uid`), which can be helpful for tasks like 
+ * generating element IDs.  
+ * {@link #module_component Component}s use `this.uid` to generate data attributes for their elements, to be looked up on hydration.  
+ * For server-side rendering, this counter should be reset to `0` on every request to ensure that the generated 
+ * unique IDs match those on the client, enabling seamless hydration of components.  
+ * @static
+ * @type {number}
+ * @default 0
  */
 View.uid = 0;
 

package/lib/core/Element.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+var utils_getAttributesDiff = require('../utils/getAttributesDiff.cjs');
+
+const SYNC_PROPS = ['value', 'checked', 'selected'];
+
+/**
+ * Element reference for managing DOM element attributes.
+ * @param {Object} options The options object.
+ * @param {Function} options.getSelector Function that returns the CSS selector for the element.
+ * @param {Function} options.getAttributes Function that returns the attributes object for the element.
+ * @private
+ */
+class Element {
+    constructor(options) {
+        this.getSelector = options.getSelector;
+        this.getAttributes = options.getAttributes;
+        this.previousAttributes = {};
+    }
+
+    /**
+     * Attach the element reference to a DOM element.
+     * @param {Node} parent The parent node to search in.
+     */
+    hydrate(parent) {
+        this.ref = parent.querySelector(this.getSelector());
+    }
+
+    /**
+     * Update the element's attributes based on the difference with previous attributes.
+     */
+    update() {
+        // Attributes diff.
+        const attributes = this.getAttributes();
+        const { remove, add } = utils_getAttributesDiff(attributes, this.previousAttributes);
+        // Store previous attributes.
+        this.previousAttributes = attributes;
+        // Remove attributes first so later `setAttribute` overrides if needed.
+        remove.forEach(attr => {
+            this.ref.removeAttribute(attr);
+            if (SYNC_PROPS.includes(attr) && attr in this.ref) {
+                // Reset property to default.
+                this.ref[attr] = attr === 'value' ? '' : false;
+            }
+        });
+        // Add / update attributes.
+        Object.keys(add).forEach(attr => {
+            const value = add[attr];
+            this.ref.setAttribute(attr, value);
+            if (SYNC_PROPS.includes(attr) && attr in this.ref) {
+                this.ref[attr] = attr === 'value' ? value : value !== false && value !== 'false';
+            }
+        });
+    }
+}
+
+module.exports = Element;

package/lib/core/EventsManager.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * Manager for delegated events.
+ * @private
+ */
+class EventsManager {
+    constructor() {
+        this.listeners = [];
+        this.types = new Set();
+        this.previousSize = 0;
+    }
+
+    /**
+     * Add a listener to the events manager.
+     * @param {Function} listener The listener to add.
+     * @param {string} type The type of event.
+     * @return {number} The index of the listener.
+     */
+    addListener(listener, type) {
+        this.types.add(type);
+        this.listeners.push(listener);
+        return this.listeners.length - 1;
+    }
+
+    /**
+     * Reset the events manager.
+     */
+    reset() {
+        this.listeners = [];
+        this.previousSize = this.types.size;
+    }
+
+    /**
+     * Check if there are pending types.
+     * @return {boolean} True if there are pending types, false otherwise.
+     */
+    hasPendingTypes() {
+        return this.types.size > this.previousSize;
+    }
+}
+
+module.exports = EventsManager;

package/lib/core/Interpolation.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+var utils_syncNode = require('../utils/syncNode.cjs');
+var utils_findComment = require('../utils/findComment.cjs');
+
+/**
+ * Interpolation reference for managing dynamic content between comment markers.
+ * Handles the lifecycle of content that can change between renders, including
+ * component recycling and DOM synchronization.
+ * @param {Object} options The options object.
+ * @param {Function} options.getStart Function that returns the start comment marker text.
+ * @param {Function} options.getEnd Function that returns the end comment marker text.
+ * @param {any} options.expression The expression to be evaluated for the interpolation.
+ * @param {Function} options.isComponent Function that checks if an element is a component root element.
+ * @param {Function} options.isElement Function that checks if an element has the Rasti data attribute.
+ * @private
+ */
+class Interpolation {
+    constructor(options) {
+        this.getStart = options.getStart;
+        this.getEnd = options.getEnd;
+        this.expression = options.expression;
+        this.isComponent = options.isComponent;
+        this.isElement = options.isElement;
+    }
+
+    /**
+     * Attach the interpolation reference to comment markers in the DOM.
+     * Searches for start and end comment markers, skipping component subtrees.
+     * @param {Node} parent The parent node to search in.
+     */
+    hydrate(parent) {
+        const startComment = utils_findComment(parent, this.getStart(), this.isComponent);
+        const endComment = utils_findComment(parent, this.getEnd(), this.isComponent, startComment);
+
+        this.ref = [
+            startComment, 
+            endComment
+        ];
+    }
+
+    /**
+     * Update the interpolation content with a new fragment.
+     * Optimizes updates by syncing single non-component elements or replacing content entirely.
+     * @param {DocumentFragment} fragment The new content fragment to insert.
+     */
+    update(fragment) {
+        const [startComment, endComment] = this.ref;
+
+        const currentFirstElement = startComment.nextSibling;
+        const currentSingleChildElement = currentFirstElement.nextSibling === endComment;
+        const currentEmpty = currentFirstElement == endComment;
+        const fragmentChildren = fragment.children;
+
+        if (currentSingleChildElement && fragmentChildren.length === 1 && !this.isElement(currentFirstElement)) {
+            // There is a single child element that is not a component's root element. Sync node attributes and content.
+            utils_syncNode(currentFirstElement, fragmentChildren[0]);
+        } else if (currentEmpty) {
+            // Interpolation is empty. Insert the fragment.
+            endComment.parentNode.insertBefore(fragment, endComment);
+        } else {
+            // Interpolation is not empty. Replace the interpolation content.
+            const range = document.createRange();
+            range.setStartAfter(startComment);
+            range.setEndBefore(endComment);
+            range.deleteContents();
+            range.insertNode(fragment);
+        }
+    }
+}
+
+module.exports = Interpolation;

package/lib/core/InterpolationWrapper.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+/**
+ * Wrapper for interpolation results with markers.
+ * @param {number} interpolationUid The interpolation UID for markers.
+ * @param {any} result The interpolation result.
+ * @private
+ */
+class InterpolationWrapper {
+    constructor(interpolationUid, result) {
+        this.interpolationUid = interpolationUid;
+        this.result = result;
+    }
+}
+
+module.exports = InterpolationWrapper;

package/lib/core/Partial.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ * Wrapper class for partial templates that preserves structure.
+ * @param {Array} items The items in the partial.
+ * @private
+ */
+class Partial {
+    constructor(items) {
+        this.items = items;
+    }
+}
+
+module.exports = Partial;

package/lib/core/PathManager.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Manager for component position tracking and recycling.
+ * @private
+ */
+class PathManager {
+    constructor() {}
+
+    /**
+     * Reset before render.
+     */
+    reset() {
+        this.paused = 0;
+        this.previous = this.tracked || new Map();
+        this.tracked = new Map();
+        this.positionStack = [0];
+    }
+
+    /**
+     * Push position to stack.
+     */
+    push() {
+        this.positionStack.push(0);
+    }
+
+    /**
+     * Pop position from stack.
+     */
+    pop() {
+        this.positionStack.pop();
+    }
+
+    /**
+     * Increment position.
+     */
+    increment() {
+        this.positionStack[this.positionStack.length - 1]++;
+    }
+
+    /**
+     * Pause tracking.
+     */
+    pause() {
+        this.paused++;
+    }
+
+    /**
+     * Resume tracking.
+     */
+    resume() {
+        this.paused--;
+    }
+
+    /**
+     * Get current path as array.
+     * @return {string} Current position path.
+     */
+    getPath() {
+        return this.positionStack.join('-');
+    }
+
+    /**
+     * Track component at current path.
+     * @param {Component} component The component to track.
+     * @return {Component} The component.
+     */
+    track(component) {
+        if (this.paused === 0) {
+            this.tracked.set(
+                this.getPath(),
+                component
+            );
+        }
+
+        return component;
+    }
+
+    /**
+     * Find recyclable component by path and type.
+     * @param {Function} constructor The component constructor.
+     * @return {Component|null} The recyclable component or null.
+     */
+    findRecyclable(constructor) {
+        const prev = this.previous.get(this.getPath());
+        return prev && prev.constructor === constructor && !prev.key ? prev : null;
+    }
+}
+
+module.exports = PathManager;

package/lib/core/SafeHTML.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Wrapper class for HTML strings marked as safe.
+ * @param {string} value The HTML string to be marked as safe.
+ * @property {string} value The HTML string.
+ * @private
+ */
+class SafeHTML {
+    constructor(value) {
+        this.value = value;
+    }
+
+    toString() {
+        return this.value;
+    }
+}
+
+module.exports = SafeHTML;

package/lib/index.cjs

@@ -4,8 +4,21 @@ var Emitter = require('./Emitter.cjs');
 var Model = require('./Model.cjs');
 var View = require('./View.cjs');
 var Component = require('./Component.cjs');
+require('./utils/validateListener.cjs');
 require('./utils/getResult.cjs');
+require('./core/SafeHTML.cjs');
+require('./core/Partial.cjs');
+require('./core/InterpolationWrapper.cjs');
+require('./core/EventsManager.cjs');
+require('./core/PathManager.cjs');
+require('./core/Element.cjs');
+require('./utils/getAttributesDiff.cjs');
+require('./core/Interpolation.cjs');
+require('./utils/syncNode.cjs');
+require('./utils/findComment.cjs');
 require('./utils/deepFlat.cjs');
+require('./utils/parseHTML.cjs');
+require('./utils/getAttributesHTML.cjs');
 
 
 

package/lib/utils/deepFlat.cjs

@@ -1,9 +1,11 @@
 'use strict';
 
-/*
- * Flatten an array recursively
+/**
+ * Flatten an array recursively.
  * @param {Array} arr Array to flat recursively
  * @return {Array} Flat array
+ * @module
+ * @private
  */
 const deepFlat = (arr) => arr.reduce((acc, val) => {
     if (Array.isArray(val)) acc.push(...deepFlat(val));

package/lib/utils/findComment.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Finds the first comment node whose text matches exactly the given `text`.
+ * Uses manual DOM traversal. Skips entire subtrees if `shouldSkip(element)` returns true.
+ * Starts searching from `startNode` if provided, otherwise from `root.firstChild`.
+ * @param {Node} root - Root node or fragment that limits the search scope.
+ * @param {string} text - Exact comment text to match.
+ * @param {Function} [shouldSkip] - Function that receives an element and returns true if its subtree should be skipped.
+ * @param {Node} [startNode] - Node to start searching from (defaults to root.firstChild).
+ * @return {Comment|null} The first matching comment node, or null if not found.
+ * @module
+ * @private
+ */
+function findComment(
+    root,
+    text,
+    shouldSkip = () => false,
+    startNode
+) {
+    let node = startNode || root.firstChild;
+
+    while (node) {
+        // Check if current node is a comment with matching text.
+        if (node.nodeType === Node.COMMENT_NODE && node.data.trim() === text) {
+            return node;
+        }
+        // Descend into children if allowed and present.
+        if (node.nodeType === Node.ELEMENT_NODE && !shouldSkip(node) && node.firstChild) {
+            node = node.firstChild;
+            continue;
+        }
+        // Move to next sibling, or climb up until a sibling is found.
+        while (node && !node.nextSibling) {
+            node = node.parentNode;
+            if (!node || node === root) return null;
+        }
+        if (node) node = node.nextSibling;
+    }
+
+    return null;
+}
+
+module.exports = findComment;