lightview 2.0.7 → 2.0.8

package/lightview.js

@@ -1,9 +1,17 @@
 (() => {
+    /**
+     * LIGHTVIEW CORE
+     * A minimalist library for signals-based reactivity and functional UI components.
+     */
+
     // ============= SIGNALS =============
 
     let currentEffect = null;
 
 
+    /**
+     * Helper to get a value from a Map or create and set it if it doesn't exist.
+     */
     const getOrSet = (map, key, factory) => {
         let v = map.get(key);
         if (!v) {
@@ -18,6 +26,11 @@
 
     const signalRegistry = new Map();
 
+    /**
+     * Creates a reactive signal.
+     * @param {*} initialValue - The initial value of the signal.
+     * @param {Object|string} [optionsOrName] - Optional name (for registry) or options object.
+     */
     const signal = (initialValue, optionsOrName) => {
         let name = typeof optionsOrName === 'string' ? optionsOrName : optionsOrName?.name;
         const storage = optionsOrName?.storage;
@@ -80,19 +93,29 @@
         return signalRegistry.get(name);
     };
 
+    /**
+     * Creates a side-effect that automatically tracks and re-runs when its signal dependencies change.
+     * @param {Function} fn - The function to execute as an effect.
+     */
     const effect = (fn) => {
         const execute = () => {
-            if (!execute.active) return;
+            if (!execute.active || execute.running) return;
             // Cleanup old dependencies
             execute.dependencies.forEach(dep => dep.delete(execute));
             execute.dependencies.clear();
 
+            execute.running = true;
             currentEffect = execute;
-            fn();
-            currentEffect = null;
+            try {
+                fn();
+            } finally {
+                currentEffect = null;
+                execute.running = false;
+            }
         };
 
         execute.active = true;
+        execute.running = false;
         execute.dependencies = new Set();
         execute.stop = () => {
             execute.dependencies.forEach(dep => dep.delete(execute));
@@ -103,12 +126,18 @@
         return execute;
     };
 
+    /**
+     * Assocates an effect with a DOM node for automatic cleanup when the node is removed.
+     */
     const trackEffect = (node, effectFn) => {
         const state = getOrSet(nodeState, node, nodeStateFactory);
         if (!state.effects) state.effects = [];
         state.effects.push(effectFn);
     };
 
+    /**
+     * Creates a read-only signal derived from other signals.
+     */
     const computed = (fn) => {
         const sig = signal(undefined);
         effect(() => {
@@ -194,20 +223,13 @@
     };
 
     // ============= REACTIVE UI =============
-    const SVG_TAGS = new Set([
-        'svg', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'g', 'defs', 'marker',
-        'pattern', 'mask', 'image', 'text', 'tspan', 'foreignObject', 'use', 'symbol', 'clipPath',
-        'linearGradient', 'radialGradient', 'stop', 'filter', 'animate', 'animateMotion',
-        'animateTransform', 'mpath', 'desc', 'metadata', 'title', 'feBlend', 'feColorMatrix',
-        'feComponentTransfer', 'feComposite', 'feConvolveMatrix', 'feDiffuseLighting',
-        'feDisplacementMap', 'feDistantLight', 'feDropShadow', 'feFlood', 'feFuncA', 'feFuncB',
-        'feFuncG', 'feFuncR', 'feGaussianBlur', 'feImage', 'feMerge', 'feMergeNode',
-        'feMorphology', 'feOffset', 'fePointLight', 'feSpecularLighting', 'feSpotLight',
-        'feTile', 'feTurbulence', 'view'
-    ]);
+    let inSVG = false;
 
     const domToElement = new WeakMap();
 
+    /**
+     * Wraps a native DOM element in a Lightview reactive proxy.
+     */
     const wrapDomElement = (domNode, tag, attributes = {}, children = []) => {
         const el = {
             tag,
@@ -220,6 +242,10 @@
         return proxy;
     };
 
+    /**
+     * The core virtual-DOM-to-real-DOM factory.
+     * Handles tag functions (components), shadow DOM directives, and SVG namespaces.
+     */
     const element = (tag, attributes = {}, children = []) => {
         if (customTags[tag]) tag = customTags[tag];
         // If tag is a function (component), call it and process the result
@@ -233,13 +259,19 @@
             return createShadowDOMMarker(attributes, children);
         }
 
-        const isSvg = SVG_TAGS.has(tag.toLowerCase());
-        const domNode = isSvg
+        const isSVG = tag.toLowerCase() === 'svg';
+        const wasInSVG = inSVG;
+        if (isSVG) inSVG = true;
+
+        const domNode = inSVG
             ? document.createElementNS('http://www.w3.org/2000/svg', tag)
             : document.createElement(tag);
+
         const proxy = wrapDomElement(domNode, tag, attributes, children);
         proxy.attributes = attributes;
         proxy.children = children;
+
+        if (isSVG) inSVG = wasInSVG;
         return proxy;
     };
 
@@ -292,6 +324,9 @@
         return null;
     };
 
+    /**
+     * Internal proxy to intercept 'attributes' and 'children' updates on an element.
+     */
     const makeReactive = (el) => {
         const domNode = el.domEl;
 
@@ -309,31 +344,25 @@
         });
     };
 
-    // Boolean attributes that should be present/absent rather than having a value
-    const BOOLEAN_ATTRIBUTES = new Set([
-        'disabled', 'checked', 'readonly', 'required', 'hidden', 'autofocus',
-        'autoplay', 'controls', 'loop', 'muted', 'default', 'defer', 'async',
-        'novalidate', 'formnovalidate', 'open', 'selected', 'multiple', 'reversed',
-        'ismap', 'nomodule', 'playsinline', 'allowfullscreen', 'inert'
-    ]);
+    // Properties that should be set directly on the DOM node object rather than as attributes
+    const NODE_PROPERTIES = new Set(['value', 'checked', 'selected', 'selectedIndex', 'className', 'innerHTML', 'innerText']);
 
     // Set attribute with proper handling of boolean attributes and undefined/null values
     const setAttributeValue = (domNode, key, value) => {
-        const isBooleanAttr = BOOLEAN_ATTRIBUTES.has(key.toLowerCase());
+        const isBool = typeof domNode[key] === 'boolean';
 
-        if (value === null || value === undefined) {
+        if (NODE_PROPERTIES.has(key) || isBool) {
+            domNode[key] = isBool ? (value !== null && value !== undefined && value !== false && value !== 'false') : value;
+        } else if (value === null || value === undefined) {
             domNode.removeAttribute(key);
-        } else if (isBooleanAttr) {
-            if (value && value !== 'false') {
-                domNode.setAttribute(key, '');
-            } else {
-                domNode.removeAttribute(key);
-            }
         } else {
             domNode.setAttribute(key, value);
         }
     };
 
+    /**
+     * Processes attributes, handling event listeners, reactive bindings, and special 'onmount' hooks.
+     */
     const makeReactiveAttributes = (attributes, domNode) => {
         const reactiveAttrs = {};
 
@@ -399,6 +428,10 @@
      * @param {boolean} clearExisting - Whether to clear existing content
      * @returns {Array} - Processed child elements
      */
+    /**
+     * Core child processing logic. Recursively handles strings, arrays, 
+     * reactive functions, vDOM objects, and Shadow DOM markers.
+     */
     const processChildren = (children, targetNode, clearExisting = true) => {
         if (clearExisting && targetNode.innerHTML !== undefined) {
             targetNode.innerHTML = ''; // Clear existing
@@ -410,19 +443,15 @@
         const isSpecialElement = targetNode.tagName &&
             (targetNode.tagName.toLowerCase() === 'script' || targetNode.tagName.toLowerCase() === 'style');
 
-        for (let child of children) {
+        const flatChildren = children.flat(Infinity);
+
+        for (let child of flatChildren) {
             // Allow extensions to transform children (e.g., template literals)
             // BUT skip for script/style elements which need raw content
             if (Lightview.hooks.processChild && !isSpecialElement) {
                 child = Lightview.hooks.processChild(child) ?? child;
             }
 
-            // Handle nested arrays (flattening)
-            if (Array.isArray(child)) {
-                childElements.push(...processChildren(child, targetNode, false));
-                continue;
-            }
-
             // Handle shadowDOM markers - attach shadow to parent and process shadow children
             if (isShadowDOMMarker(child)) {
                 // targetNode is the parent element that should get the shadow root
@@ -437,45 +466,40 @@
 
             const type = typeof child;
             if (type === 'function') {
-                const result = child();
-                // Determine if the result implies complex content (DOM/vDOM/Array)
-                // Treat as complex if it's an object (including arrays) but not null
-                const isComplex = result && (typeof result === 'object' || Array.isArray(result));
-
-                if (isComplex) {
-                    // Reactive element, vDOM object, or list of items
-                    // Use a stable wrapper div to hold the reactive content
-                    const wrapper = document.createElement('span');
-                    wrapper.style.display = 'contents';
-                    targetNode.appendChild(wrapper);
-
-                    let runner;
-                    const update = () => {
-                        const val = child();
-                        // Check if wrapper is still in the DOM (skip check on first run)
-                        if (runner && !wrapper.parentNode) {
-                            runner.stop();
-                            return;
-                        }
-                        const childrenToProcess = Array.isArray(val) ? val : [val];
-                        // processChildren handles clearing existing content via 3rd arg=true
-                        processChildren(childrenToProcess, wrapper, true);
-                    };
-
-                    runner = effect(update);
-                    trackEffect(wrapper, runner);
-                    childElements.push(child);
-                } else {
-                    // Reactive text node for primitives
-                    const textNode = document.createTextNode('');
-                    targetNode.appendChild(textNode);
-                    const runner = effect(() => {
-                        const val = child();
-                        textNode.textContent = val !== undefined ? val : '';
-                    });
-                    trackEffect(textNode, runner);
-                    childElements.push(child);
-                }
+                const startMarker = document.createComment('lv:s');
+                const endMarker = document.createComment('lv:e');
+                targetNode.appendChild(startMarker);
+                targetNode.appendChild(endMarker);
+
+                let runner;
+                const update = () => {
+                    // 1. Cleanup: Remove everything between markers
+                    while (startMarker.nextSibling && startMarker.nextSibling !== endMarker) {
+                        startMarker.nextSibling.remove();
+                        // Note: MutationObserver handles cleanupNode(removedNode)
+                    }
+
+                    // 2. Execution: Get new value and process it
+                    const val = child();
+                    if (val === undefined || val === null) return;
+
+                    // 3. Render: Process children into a fragment and insert before endMarker
+                    const fragment = document.createDocumentFragment();
+                    const childrenToProcess = Array.isArray(val) ? val : [val];
+
+                    // Stop the runner if the markers are no longer in the DOM
+                    if (runner && !startMarker.isConnected) {
+                        runner.stop();
+                        return;
+                    }
+
+                    processChildren(childrenToProcess, fragment, false);
+                    endMarker.parentNode.insertBefore(fragment, endMarker);
+                };
+
+                runner = effect(update);
+                trackEffect(startMarker, runner);
+                childElements.push(child);
             } else if (['string', 'number', 'boolean', 'symbol'].includes(type)) {
                 // Static text
                 targetNode.appendChild(document.createTextNode(child));
@@ -507,6 +531,9 @@
     };
 
     // ============= EXPORTS =============
+    /**
+     * Enhances an existing DOM element with Lightview reactivity.
+     */
     const enhance = (selectorOrNode, options = {}) => {
         const domNode = typeof selectorOrNode === 'string'
             ? document.querySelector(selectorOrNode)
@@ -549,6 +576,9 @@
         return el;
     };
 
+    /**
+     * Query selector helper that adds a .content() method for easy DOM manipulation.
+     */
     const $ = (cssSelectorOrElement, startingDomEl = document.body) => {
         const el = typeof cssSelectorOrElement === 'string' ? startingDomEl.querySelector(cssSelectorOrElement) : cssSelectorOrElement;
         if (!el) return null;
@@ -574,37 +604,19 @@
                     }
                 });
 
-                if (location === 'shadow') {
-                    let shadow = el.shadowRoot;
-                    if (!shadow) {
-                        shadow = el.attachShadow({ mode: 'open' });
-                    }
-                    shadow.innerHTML = '';
-                    array.forEach(item => {
-                        shadow.appendChild(item);
-                    });
-                    return el;
-                }
-
-                if (location === 'inner') {
-                    el.innerHTML = '';
-                    array.forEach(item => {
-                        el.appendChild(item);
-                    });
-                    return el;
-                }
-
-                if (location === 'outer') {
-                    el.replaceWith(...array);
-                    return el;
-                }
+                const target = location === 'shadow' ? (el.shadowRoot || el.attachShadow({ mode: 'open' })) : el;
 
-                if (location === 'afterbegin' || location === 'afterend') {
-                    array.reverse();
+                if (location === 'inner' || location === 'shadow') {
+                    target.replaceChildren(...array);
+                } else if (location === 'outer') {
+                    target.replaceWith(...array);
+                } else if (location === 'afterbegin') {
+                    target.prepend(...array);
+                } else if (location === 'beforeend') {
+                    target.append(...array);
+                } else {
+                    array.forEach(item => el.insertAdjacentElement(location, item));
                 }
-                array.forEach(item => {
-                    el.insertAdjacentElement(location, item);
-                });
                 return el;
             },
             configurable: true,
@@ -614,6 +626,10 @@
     };
 
     const customTags = {}
+    /**
+     * Proxy for accessing or registering tags/components.
+     * e.g., Lightview.tags.div(...) or Lightview.tags.MyComponent = ...
+     */
     const tags = new Proxy({}, {
         get(_, tag) {
             if (tag === "_customTags") return { ...customTags };
@@ -626,7 +642,7 @@
                     attributes = arg0;
                     children = args.slice(1);
                 }
-                return element(customTags[tag] || tag, attributes, children.flat());
+                return element(customTags[tag] || tag, attributes, children);
             };
 
             // Lift static methods/properties from the component onto the wrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightview",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "A lightweight reactive UI library with features of Bau, Juris, and HTMX",
   "main": "lightview.js",
   "directories": {