apprun 3.36.0 → 3.36.1

package/src/vdom-my-prop-attr.ts

@@ -0,0 +1,241 @@
+/**
+ * VDOM Property and Attribute Handler
+ * Standards-compliant property/attribute handling with caching and special element support
+ * Features: Skip logic for preserving user interactions during VDOM reconciliation
+ * Exports: updateProps - Main function for DOM element property updates
+ * Updated: 2025-01-14 - Added skip logic for focus-sensitive, scroll, and media properties
+ */
+
+import { find, html, svg } from 'property-information';
+
+const ATTR_PROPS = '_props';
+const propertyInfoCache = new Map<string, any>();
+
+// Merge old and new props, handling className -> class conversion and null cleanup
+function mergeProps(oldProps: { [key: string]: any }, newProps: { [key: string]: any }): { [key: string]: any } {
+  if (newProps) {
+    newProps['class'] = newProps['class'] || newProps['className'];
+    delete newProps['className'];
+  }
+
+  if (!oldProps || Object.keys(oldProps).length === 0) return newProps || {};
+  if (!newProps || Object.keys(newProps).length === 0) {
+    const props: { [key: string]: any } = {};
+    Object.keys(oldProps).forEach(p => props[p] = null);
+    return props;
+  }
+
+  const props: { [key: string]: any } = {};
+  Object.keys(oldProps).forEach(p => {
+    if (!(p in newProps)) props[p] = null;
+  });
+  Object.keys(newProps).forEach(p => props[p] = newProps[p]);
+  return props;
+}
+
+// Convert kebab-case to camelCase for dataset keys
+function convertKebabToCamelCase(str: string): string {
+  if (str.length <= 1) return str.toLowerCase();
+  return str.split('-').map((word, index) =>
+    index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+  ).join('');
+}
+
+// Cached property information lookup
+function getPropertyInfo(name: string, isSvg: boolean) {
+  const cacheKey = `${name}:${isSvg}`;
+  let info = propertyInfoCache.get(cacheKey);
+  if (info === undefined) {
+    info = find(isSvg ? svg : html, name) || null;
+    propertyInfoCache.set(cacheKey, info);
+  }
+  return info;
+}
+
+
+// Specialized handlers for different attribute types
+function setDatasetAttribute(element: Element, attributeName: string, value: any): void {
+  const camelKey = convertKebabToCamelCase(attributeName.slice(5));
+  if (value == null) {
+    delete (element as HTMLElement).dataset[camelKey];
+  } else {
+    (element as HTMLElement).dataset[camelKey] = String(value);
+  }
+}
+
+function setEventHandler(element: Element, name: string, value: any): void {
+  if (!name.startsWith('on')) return;
+
+  if (!value || typeof value === 'function') {
+    (element as any)[name] = value;
+  } else if (typeof value === 'string') {
+    if (value) element.setAttribute(name, value);
+    else element.removeAttribute(name);
+  }
+}
+
+function setBooleanAttribute(element: Element, attributeName: string, value: any): void {
+  if (shouldSetBooleanAttribute(value)) {
+    element.setAttribute(attributeName, attributeName);
+  } else {
+    element.removeAttribute(attributeName);
+  }
+}
+
+function setElementProperty(element: Element, propertyName: string, value: any): void {
+  try {
+    (element as any)[propertyName] = value;
+  } catch (error) {
+    setElementAttribute(element, propertyName, value, false);
+  }
+}
+
+function setElementAttribute(element: Element, attributeName: string, value: any, isSvg: boolean): void {
+  if (value == null) {
+    element.removeAttribute(attributeName);
+    return;
+  }
+
+  const stringValue = String(value);
+  if (isSvg && attributeName.includes(':')) {
+    const [prefix] = attributeName.split(':');
+    if (prefix === 'xlink') {
+      element.setAttributeNS('http://www.w3.org/1999/xlink', attributeName, stringValue);
+    } else {
+      element.setAttribute(attributeName, stringValue);
+    }
+  } else {
+    element.setAttribute(attributeName, stringValue);
+  }
+}
+
+function shouldSetBooleanAttribute(value: any): boolean {
+  if (value == null || value === false || value === '') return false;
+  if (value === true) return true;
+  if (typeof value === 'string') {
+    const lowerValue = value.toLowerCase();
+    return lowerValue !== 'false' && value !== '0';
+  }
+  return Boolean(value);
+}
+
+// Core property/attribute setting function - handles all property types with skip logic
+function setAttributeOrProperty(element: Element, name: string, value: any, isSvg: boolean): void {
+  // Check if we should skip this property update to preserve user interaction
+  if (shouldSkipPatch(element as HTMLElement, name)) {
+    return;
+  }
+
+  // Special cases with dedicated handling
+  if (name === 'style') {
+    if ((element as HTMLElement).style.cssText) (element as HTMLElement).style.cssText = '';
+    if (typeof value === 'string') (element as HTMLElement).style.cssText = value;
+    else if (value && typeof value === 'object') {
+      for (const s in value) {
+        if ((element as HTMLElement).style[s] !== value[s]) (element as HTMLElement).style[s] = value[s];
+      }
+    }
+    return;
+  }
+
+  if (name === 'key') {
+    if (value !== undefined && value !== null) (element as any).key = value;
+    return;
+  }
+
+  if (name.startsWith('data-')) {
+    setDatasetAttribute(element, name, value);
+    return;
+  }
+
+  if (name.startsWith('on')) {
+    setEventHandler(element, name, value);
+    return;
+  }
+
+  // Form elements with special property requirements
+  if ((element.tagName === 'INPUT' || element.tagName === 'TEXTAREA' || element.tagName === 'SELECT') &&
+    (name === 'value' || name === 'selected' || name === 'selectedIndex')) {
+    setElementProperty(element, name, value);
+    return;
+  }
+
+  // Input checked needs both property and attribute
+  if (element.tagName === 'INPUT' && name === 'checked') {
+    setElementProperty(element, name, value);
+    setBooleanAttribute(element, name, value);
+    return;
+  }
+
+  // Use property information for standard attributes
+  const info = getPropertyInfo(name, isSvg);
+  if (info) {
+    if (info.boolean || info.overloadedBoolean) {
+      setBooleanAttribute(element, info.attribute, value);
+    } else if (info.mustUseProperty && !isSvg) {
+      setElementProperty(element, info.property, value);
+    } else {
+      setElementAttribute(element, info.attribute, value, isSvg);
+    }
+  } else {
+    // Fallback handling for unknown attributes
+    if (name.startsWith('aria-') || name === 'role') {
+      setElementAttribute(element, name, value, isSvg);
+    } else if (name in element || (element as any)[name] !== undefined) {
+      setElementProperty(element, name, value);
+    } else {
+      setElementAttribute(element, name, value, isSvg);
+    }
+  }
+}
+
+// Skip logic for preventing user interaction disruption during VDOM reconciliation
+function shouldSkipPatch(dom: HTMLElement, prop: string): boolean {
+  if (document.activeElement === dom) {
+    return ['value', 'selectionStart', 'selectionEnd', 'selectionDirection']
+      .includes(prop);
+  }
+  if (prop === 'scrollTop' || prop === 'scrollLeft') {
+    return true;
+  }
+  if (dom instanceof HTMLMediaElement &&
+    ['currentTime', 'paused', 'playbackRate', 'volume'].includes(prop)) {
+    return true;
+  }
+  return false;           // default: allow normal diff logic
+}
+
+function isValidAttributeName(name: string): boolean {
+  return /^[a-zA-Z_:][\w\-:.]*$/.test(name) &&
+    !name.includes('<') && !name.includes('>') && !name.includes('"') && !name.includes("'");
+}
+
+
+// Main exported function for updating element properties
+export function updateProps(element: Element, props: { [key: string]: any }, isSvg: boolean): void {
+  // console.assert(!!element);
+  const cached = element[ATTR_PROPS] || {};
+  const merged = mergeProps(cached, props);
+  element[ATTR_PROPS] = props || {};
+
+  applyPropertiesToElement(element, merged, props, isSvg);
+}
+
+// Apply merged properties to element with ref handling
+function applyPropertiesToElement(
+  element: Element,
+  mergedProps: { [key: string]: any },
+  originalProps: { [key: string]: any } | null,
+  isSvg: boolean
+): void {
+  for (const name in mergedProps) {
+    if (isValidAttributeName(name)) {
+      setAttributeOrProperty(element, name, mergedProps[name], isSvg);
+    }
+  }
+
+  // Handle ref callback
+  if (mergedProps && typeof mergedProps['ref'] === 'function') {
+    window.requestAnimationFrame(() => mergedProps['ref'](element));
+  }
+}

package/src/vdom-my.ts

@@ -1,13 +1,56 @@
+/** * VDOM Implementation for AppRun
+ * 
+ * Notes for AppRun’s key prop
+ * Use the key prop only if you need to preserve browser-side DOM state (such as cursor 
+ * position in an <input>, focus, or maintaining state in inline components).
+ *
+ * For most use cases, especially with stateless or purely data-driven UIs, key is not
+ * needed and may decrease performance by forcing DOM moves.
+ *
+ * AppRun aggressively updates DOM to match your vdom, so DOM node preservation is
+ * only valuable when you intentionally depend on browser-managed state.
+ *
+ * | Use Case                      | Should I use `key`? | Why                   |
+ * | ----------------------------- | ------------------- | --------------------- |
+ * | Preserve input cursor/focus   | ✅ Yes               | Keeps browser state   |
+ * | Inline stateful component     | ✅ Yes               | Preserves component   |
+ * | Regular data list (stateless) | 🚫 No               | Unnecessary DOM moves |  
+ * | Purely visual updates         | 🚫 No               | No state to preserve  |
+ * 
+ * Features:
+ * - Virtual DOM rendering and diffing for efficient DOM updates
+ * - JSX Fragment support for both Babel and TypeScript
+ * - Element creation with props, children, and event handling
+ * - SVG element support with proper namespace handling
+ * - Component lifecycle management and caching
+ * - Keyed element optimization with automatic cleanup for memory management
+ * - Safe HTML insertion and text node creation
+ * - Directive processing integration
+ * 
+ * Implementation:
+ * - Uses plain JavaScript object for keyCache instead of Map for better performance
+ * - Implements automatic cleanup of disconnected elements from keyCache
+ * - Supports both string and function-based tags
+ * - Handles component mounting and state management
+ * - Optimized children updating with minimal DOM operations
+ * - Memory-efficient caching with configurable thresholds (500 ops, 1000 max size)
+ * 
+ * Recent Changes:
+ * - 2025-07-15: Converted keyCache from Map to plain object ({}) for improved performance
+ * - Updated cleanup functions to use object property deletion instead of Map methods
+ * - Enhanced memory management with automatic cleanup of disconnected elements
+ * - Added comprehensive key prop usage documentation and guidelines
+ */
+
 import { VDOM, VNode } from './types';
 import directive from './directive';
+import { updateProps } from './vdom-my-prop-attr';
 export type Element = any; //HTMLElement | SVGSVGElement | SVGElement;
 
 export function Fragment(props, ...children): any[] {
   return collect(children);
 }
 
-const ATTR_PROPS = '_props';
-
 function collect(children) {
   const ch = [];
   const push = (c) => {
@@ -25,6 +68,30 @@ function collect(children) {
   return ch;
 }
 
+const keyCache: { [key: string]: Element } = {};
+let cleanupCounter = 0;
+const CLEANUP_THRESHOLD = 500; // Cleanup every 500 operations
+const MAX_CACHE_SIZE = 1000;
+
+// Lightweight cleanup function - only runs when needed
+function cleanupKeyCache() {
+  if (Object.keys(keyCache).length <= MAX_CACHE_SIZE) return; // Skip if under limit
+
+  for (const [key, element] of Object.entries(keyCache)) {
+    if (!element.isConnected) {
+      delete keyCache[key];
+    }
+  }
+}
+
+// Export cleanup function for manual cleanup if needed
+export function clearKeyCache() {
+  for (const key in keyCache) {
+    delete keyCache[key];
+  }
+  cleanupCounter = 0;
+}
+
 export function createElement(tag: string | Function | [], props?: {}, ...children) {
   const ch = collect(children);
   if (typeof tag === 'string') return { tag, props, children: ch };
@@ -35,8 +102,6 @@ export function createElement(tag: string | Function | [], props?: {}, ...childr
   else throw new Error(`Unknown tag in vdom ${tag}`);
 };
 
-const keyCache = {};
-
 export const updateElement = (element: Element | string, nodes: VDOM, component = {}) => {
   // tslint:disable-next-line
   if (nodes == null || nodes === false) return;
@@ -77,86 +142,56 @@ function update(element: Element, node: VNode, isSvg: boolean) {
   updateProps(element, node.props, isSvg);
 }
 
-function updateChildren(element: Element, children: any[], isSvg: boolean) {
+function updateChildren(element, children, isSvg: boolean) {
   const old_len = element.childNodes?.length || 0;
   const new_len = children?.length || 0;
-
-  // Handle key-based reordering first if any children have keys
-  const hasKeysInNewChildren = children?.some(child =>
-    child && typeof child === 'object' && child.props && child.props.key !== undefined
-  );
-
-  if (hasKeysInNewChildren) {
-    // Create a map of existing keyed elements
-    const existingKeyedElements = new Map();
-    for (let i = 0; i < old_len; i++) {
-      const el = element.childNodes[i];
-      if (el && el.key) {
-        existingKeyedElements.set(el.key, el);
-      }
-    }
-
-    // Build new DOM structure
-    const fragment = document.createDocumentFragment();
-    for (let i = 0; i < new_len; i++) {
-      const child = children[i];
-      if (child == null) continue;
-
-      const key = child.props && child.props['key'];
-      if (key && existingKeyedElements.has(key)) {
-        // Reuse existing element
-        const existingEl = existingKeyedElements.get(key);
-        update(existingEl, child as VNode, isSvg);
-        fragment.appendChild(existingEl);
-        existingKeyedElements.delete(key); // Mark as used
-      } else {
-        // Create new element
-        fragment.appendChild(create(child, isSvg));
-      }
-    }
-
-    // Clear current children and append new structure
-    while (element.firstChild) {
-      element.removeChild(element.firstChild);
-    }
-    element.appendChild(fragment);
-    return;
-  }
-
-  // Original non-keyed logic
   const len = Math.min(old_len, new_len);
   for (let i = 0; i < len; i++) {
     const child = children[i];
-    if (child == null) continue;
     const el = element.childNodes[i];
-    if (!el) continue; // Safety check for undefined childNodes
     if (typeof child === 'string') {
-      if (el.nodeType === 3) {
-        if (el.nodeValue !== child) {
-          el.nodeValue = child;
+      if (el.textContent !== child) {
+        if (el.nodeType === 3) {
+          el.nodeValue = child
+        } else {
+          element.replaceChild(createText(child), el);
         }
-      } else {
-        element.replaceChild(createText(child), el);
       }
     } else if (child instanceof HTMLElement || child instanceof SVGElement) {
-      element.replaceChild(child, el);
-    } else if (child && typeof child === 'object') {
-      update(element.childNodes[i], child as VNode, isSvg);
+      element.insertBefore(child, el);
+    } else {
+      const key = child.props && child.props['key'];
+      if (key) {
+        if (el.key === key) {
+          update(element.childNodes[i], child, isSvg);
+        } else {
+          // console.log(el.key, key);
+          const old = keyCache[key];
+          if (old) {
+            // const temp = old.nextSibling;
+            element.insertBefore(old, el);
+            // temp ? element.insertBefore(el, temp) : element.appendChild(el);
+            update(element.childNodes[i], child, isSvg);
+          } else {
+            element.replaceChild(create(child, isSvg), el);
+          }
+        }
+      } else {
+        update(element.childNodes[i], child, isSvg);
+      }
     }
   }
 
-  // Remove extra old nodes
-  while (element.childNodes.length > len) {
+  let n = element.childNodes?.length || 0;
+  while (n > len) {
     element.removeChild(element.lastChild);
+    n--;
   }
 
   if (new_len > len) {
     const d = document.createDocumentFragment();
     for (let i = len; i < children.length; i++) {
-      const child = children[i];
-      if (child != null) {
-        d.appendChild(create(child, isSvg));
-      }
+      d.appendChild(create(children[i], isSvg));
     }
     element.appendChild(d);
   }
@@ -182,12 +217,7 @@ function create(node: VNode | string | HTMLElement | SVGElement, isSvg: boolean)
   // console.assert(node !== null && node !== undefined);
   if ((node instanceof HTMLElement) || (node instanceof SVGElement)) return node;
   if (typeof node === "string") return createText(node);
-
-  // Type guard for VNode objects - handle invalid node types gracefully
-  if (!node || typeof node !== 'object' || !node.tag || (typeof node.tag === 'function')) {
-    return createText(typeof node === 'object' ? JSON.stringify(node) : String(node ?? ''));
-  }
-
+  if (!node.tag || (typeof node.tag === 'function')) return createText(JSON.stringify(node));
   isSvg = isSvg || node.tag === "svg";
   const element = isSvg
     ? document.createElementNS("http://www.w3.org/2000/svg", node.tag)
@@ -195,73 +225,18 @@ function create(node: VNode | string | HTMLElement | SVGElement, isSvg: boolean)
 
   updateProps(element, node.props, isSvg);
   if (node.children) node.children.forEach(child => element.appendChild(create(child, isSvg)));
-  return element
-}
 
-function mergeProps(oldProps: {}, newProps: {}): {} {
-  newProps['class'] = newProps['class'] || newProps['className'];
-  delete newProps['className'];
-  const props = {};
-  if (oldProps) Object.keys(oldProps).forEach(p => props[p] = null);
-  if (newProps) Object.keys(newProps).forEach(p => props[p] = newProps[p]);
-  return props;
-}
-
-export function updateProps(element: Element, props: {}, isSvg) {
-  // console.assert(!!element);
-  const cached = element[ATTR_PROPS] || {};
-  props = mergeProps(cached, props || {});
-  element[ATTR_PROPS] = props;
+  if (node.props && (node.props as any).key !== undefined) {
+    (element as any).key = (node.props as any).key;
+    keyCache[(node.props as any).key] = element;
 
-  for (const name in props) {
-    const value = props[name];
-    // if (cached[name] === value) continue;
-    // console.log('updateProps', name, value);
-    if (name.startsWith('data-')) {
-      const dname = name.substring(5);
-      const cname = dname.replace(/-(\w)/g, (match) => match[1].toUpperCase());
-      if (element.dataset[cname] !== value) {
-        if (value || value === "") element.dataset[cname] = value;
-        else delete element.dataset[cname];
-      }
-    } else if (name === 'style') {
-      if (element.style.cssText) element.style.cssText = '';
-      if (typeof value === 'string') element.style.cssText = value;
-      else {
-        for (const s in value) {
-          if (element.style[s] !== value[s]) element.style[s] = value[s];
-        }
-      }
-    } else if (name.startsWith('xlink')) {
-      const xname = name.replace('xlink', '').toLowerCase();
-      if (value == null || value === false) {
-        element.removeAttributeNS('http://www.w3.org/1999/xlink', xname);
-      } else {
-        element.setAttributeNS('http://www.w3.org/1999/xlink', xname, value);
-      }
-    } else if (name.startsWith('on')) {
-      if (!value || typeof value === 'function') {
-        element[name] = value;
-      } else if (typeof value === 'string') {
-        if (value) element.setAttribute(name, value);
-        else element.removeAttribute(name);
-      }
-    } else if (/^id$|^class$|^list$|^readonly$|^contenteditable$|^role|-|^for$/g.test(name) || isSvg) {
-      if (element.getAttribute(name) !== value) {
-        if (value) element.setAttribute(name, value);
-        else element.removeAttribute(name);
-      }
-    } else if (element[name] !== value) {
-      element[name] = value;
+    // Lightweight cleanup - only when counter reaches threshold
+    if (++cleanupCounter >= CLEANUP_THRESHOLD) {
+      cleanupKeyCache();
+      cleanupCounter = 0;
     }
-    if (name === 'key' && value !== undefined) {
-      keyCache[value] = element;
-      element.key = value; // Set key property on the DOM element
-    }
-  }
-  if (props && typeof props['ref'] === 'function') {
-    window.requestAnimationFrame(() => props['ref'](element));
   }
+  return element
 }
 
 function render_component(node, parent, idx) {

package/src/version.ts

@@ -10,7 +10,7 @@
 
 // Import version from package.json to maintain single source of truth
 // This version string is used across the framework
-export const APPRUN_VERSION = '3.36.0';
+export const APPRUN_VERSION = '3.36.1';
 
 // Version string with prefix for global tracking
 export const APPRUN_VERSION_GLOBAL = `AppRun-${APPRUN_VERSION}`;

package/cli/export.js

@@ -1,92 +0,0 @@
-import { exec } from 'child_process';
-import yaml from 'js-yaml';
-import { unlinkSync } from 'fs';
-
-function replacer(key, value) {
-  if (typeof value === 'function') return value.toString();
-  return ['', null].includes(value) || (typeof value === 'object' && (value.length === 0 || Object.keys(value).length === 0)) ? undefined : value;
-}
-
-function createProxy(obj) {
-  const handler = {
-    get(target, property, receiver) {
-
-      // Get the property value
-      const value = Reflect.get(target, property, receiver);
-
-      // If the value is an object (including arrays), proxy it
-      if (typeof value === 'object' && value !== null) {
-        if (Array.isArray(value)) {
-          // Proxy each element of the array if it's an object
-          return value.map(item => createProxy(item));
-        } else {
-          // Recursively proxy the object
-          return createProxy(value);
-        }
-      }
-
-      return `{${property}}`
-    },
-
-  };
-
-  return Array.isArray(obj) ?
-    obj.map(item => createProxy(item)) : new Proxy(obj, handler);
-}
-
-function getVDOM(component) {
-  let view;
-  if (typeof component.state === 'object') {
-    const proxy = createProxy(component.state);
-    view = component.view(proxy);
-  } else {
-    view = component.view(component.state);
-  }
-  return view;
-}
-
-export default function export_yaml(fn) {
-
-  const tmp = process.cwd() + '/_tmp.js';
-  exec(`npx esbuild ${fn} --outfile=${tmp} --format=esm --bundle`, (error, stdout, stderr) => {
-    if (error) {
-      console.error(`exec error: ${error}`);
-      return;
-    }
-
-    import(tmp).then((m) => {
-
-      const defaul_export = m.default
-      let component;
-      if (typeof defaul_export === 'function' &&
-        /^class\s/.test(Function.prototype.toString.call(defaul_export))) {
-        component = new m.default();
-        component = component.mount();
-      } else if (typeof defaul_export === 'function') {
-        component = defaul_export();
-      } else {
-        component = defaul_export;
-      }
-
-      const vdom = getVDOM(component);
-      const events = component['_actions'].map(a => a.name);
-
-      const component_def = {
-        name: component.constructor.name,
-        file: fn,
-        state: component.state,
-        view: vdom,
-        actions: events,
-        update: component.update,
-      };
-
-      const yaml_def = yaml.dump(component_def, { replacer });
-      console.log(yaml_def);
-
-      unlinkSync(tmp);
-    });
-  });
-}
-
-
-