apprun 3.35.0 → 3.36.1

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 = new WeakMap();
-
 export const updateElement = (element: Element | string, nodes: VDOM, component = {}) => {
   // tslint:disable-next-line
   if (nodes == null || nodes === false) return;
@@ -67,15 +132,14 @@ function same(el: Element, node: VNode) {
 }
 
 function update(element: Element, node: VNode, isSvg: boolean) {
-  if (node['_op'] === 3) return;
   // console.assert(!!element);
   isSvg = isSvg || node.tag === "svg";
   if (!same(element, node)) {
     element.parentNode.replaceChild(create(node, isSvg), element);
     return;
   }
-  !(node['_op'] & 2) && updateChildren(element, node.children, isSvg);
-  !(node['_op'] & 1) && updateProps(element, node.props, isSvg);
+  updateChildren(element, node.children, isSvg);
+  updateProps(element, node.props, isSvg);
 }
 
 function updateChildren(element, children, isSvg: boolean) {
@@ -84,7 +148,6 @@ function updateChildren(element, children, isSvg: boolean) {
   const len = Math.min(old_len, new_len);
   for (let i = 0; i < len; i++) {
     const child = children[i];
-    if (child['_op'] === 3) continue;
     const el = element.childNodes[i];
     if (typeof child === 'string') {
       if (el.textContent !== child) {
@@ -105,9 +168,9 @@ function updateChildren(element, children, isSvg: boolean) {
           // console.log(el.key, key);
           const old = keyCache[key];
           if (old) {
-            const temp = old.nextSibling;
+            // const temp = old.nextSibling;
             element.insertBefore(old, el);
-            temp ? element.insertBefore(el, temp) : element.appendChild(el);
+            // temp ? element.insertBefore(el, temp) : element.appendChild(el);
             update(element.childNodes[i], child, isSvg);
           } else {
             element.replaceChild(create(child, isSvg), el);
@@ -146,7 +209,7 @@ function createText(node) {
     div.insertAdjacentHTML('afterbegin', node.substring(6))
     return div;
   } else {
-    return document.createTextNode(node??'');
+    return document.createTextNode(node ?? '');
   }
 }
 
@@ -162,70 +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) keyCache[value] = element;
-  }
-  if (props && typeof props['ref'] === 'function') {
-    window.requestAnimationFrame(() => props['ref'](element));
   }
+  return element
 }
 
 function render_component(node, parent, idx) {

package/src/version.ts

@@ -0,0 +1,16 @@
+/**
+ * Version Management Utility
+ * 
+ * Single source of truth for AppRun version information.
+ * This file ensures version consistency across all modules.
+ * 
+ * The version is derived from package.json and should be updated
+ * only when the package version changes.
+ */
+
+// 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.1';
+
+// Version string with prefix for global tracking
+export const APPRUN_VERSION_GLOBAL = `AppRun-${APPRUN_VERSION}`;

package/src/web-component.ts

@@ -4,30 +4,50 @@
  * This file enables using AppRun components as Web Components:
  * 1. Custom Element Creation
  *    - Converts AppRun components to custom elements
- *    - Handles lifecycle (connected, disconnected, etc)
- *    - Manages shadow DOM and light DOM rendering
+ *    - Handles lifecycle (connected, disconnected, attributeChanged)
+ *    - Manages shadow DOM and light DOM rendering options
+ *    - Automatic element registration with customElements.define()
  * 
  * 2. Property/Attribute Sync
- *    - Observes attribute changes
- *    - Updates component state automatically
- *    - Handles camelCase/kebab-case conversion
- *    - Supports complex property types
+ *    - Observes attribute changes with attributeChangedCallback
+ *    - Updates component state automatically on changes
+ *    - Handles camelCase/kebab-case conversion automatically
+ *    - Supports complex property types and JSON parsing
+ *    - Two-way data binding between attributes and state
  * 
  * 3. Event Handling
  *    - Proxies events between component and element
- *    - Supports both global and local events
- *    - Maintains proper event bubbling
+ *    - Supports both global and local event systems
+ *    - Maintains proper event bubbling and capturing
+ *    - Custom event dispatching for component communication
  * 
+ * Features:
+ * - Shadow DOM encapsulation support
+ * - Attribute observation and change detection
+ * - Lifecycle management and cleanup
+ * - Property reflection to attributes
+ * - Event proxy system
+ * - Flexible rendering options
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Enhanced custom element options typing
+ * - Better lifecycle method signatures
+ * - Improved attribute/property type safety
+ * - Safer DOM manipulation with null checks
+ *
  * Usage:
  * ```ts
  * // Register web component
- * @customElement('my-element')
+ * @customElement('my-element', { 
+ *   shadow: true,
+ *   observedAttributes: ['name', 'value']
+ * })
  * class MyComponent extends Component {
  *   // Regular AppRun component code
  * }
  * 
  * // Use in HTML
- * <my-element name="value"></my-element>
+ * <my-element name="value" data-prop="complex"></my-element>
  * ```
  */
 
@@ -71,7 +91,7 @@ export const customElement = (componentClass, options: CustomElementOptions = {}
         }
         return map
       }, {})
-      this._attrMap = (name: string) : string => attrMap[name] || name
+      this._attrMap = (name: string): string => attrMap[name] || name
 
       const props = {};
       Array.from(this.attributes).forEach(item => props[this._attrMap(item.name)] = item.value);

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);
-    });
-  });
-}
-
-
-

package/cli/import.js

@@ -1,68 +0,0 @@
-import ymal from 'js-yaml';
-import { readFileSync } from 'fs';
-
-function getProp(prop) {
-  if (typeof prop === 'object') {
-    return Object.keys(prop).map(name => `${name}:${prop[name]}`).join(';');
-  }
-  else return prop.toString();
-}
-
-function toProps(props) {
-  return Object.keys(props)
-    .map(name => ` ${name === 'className' ? 'class' : name}="${getProp(props[name])}"`)
-    .join('');
-}
-
-function toHTMLArray(nodes) {
-  return nodes.map(node => toHTML(node)).join('');
-}
-
-function toHTML(vdom) {
-  if (!vdom) return '';
-  if (Array.isArray(vdom)) return toHTMLArray(vdom)
-  if (vdom.tag) {
-    const props = vdom.props ? toProps(vdom.props) : '';
-    const children = vdom.children ? toHTMLArray(vdom.children) : '';
-    return `<${vdom.tag}${props}>${children}</${vdom.tag}>`;
-  }
-  if (typeof vdom === 'object') return JSON.stringify(vdom);
-  else {
-    const html = vdom.toString();
-    return html.startsWith('_html:') ? html.substring(6) : html;
-  }
-}
-
-export default function import_yaml(fn) {
-
-  const def = ymal.load(readFileSync(fn, 'utf8'))
-
-  const { name, state, view, update } = def;
-
-  const jsx = toHTML(view);
-
-  // const update_text = JSON.stringify(update, null, 2)
-  //   .replace(/\\n/g, '\n');
-
-  const update_text =
-  Object.keys(update).map(key => `
-    "${key}" : ${update[key].replace(/\\n/g, '\n')}`).join(',\n'
-  );
-
-  const component = `
-  import { app, Component } from 'apprun';
-
-  class ${name} extends Component {
-
-    state = ${JSON.stringify(state)};
-
-    view = ${jsx};
-
-    update = {
-      ${update_text}
-    };
-  };
-`;
-
-  console.log(component);
-}