apprun 3.36.0 → 3.37.0

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.37.0';
 
 // Version string with prefix for global tracking
 export const APPRUN_VERSION_GLOBAL = `AppRun-${APPRUN_VERSION}`;

package/src/web-component.ts

@@ -53,18 +53,12 @@
 
 declare var customElements;
 
-export type CustomElementOptions = {
-  render?: boolean;
-  shadow?: boolean;
-  history?: boolean;
-  global_event?: boolean;
-  observedAttributes?: string[];
-};
+import { CustomElementOptions } from './types';
 
 export const customElement = (componentClass, options: CustomElementOptions = {}) => class CustomElement extends HTMLElement {
-  private _shadowRoot;
-  private _component;
-  private _attrMap: (arg0: string) => string;
+  public _shadowRoot;
+  public _component;
+  public _attrMap: (arg0: string) => string;
   public on;
   public run;
   constructor() {

package/tsconfig.jest.json

@@ -1,17 +1,21 @@
 {
 	"compilerOptions": {
-		"target": "es2015",
-		"module": "es2015",
+		"target": "es2020",
+		"module": "esnext",
 		"moduleResolution": "node",
 		"jsx": "react",
 		"reactNamespace": "app",
-		"lib": ["dom", "esnext"],
+		"lib": [
+			"dom",
+			"esnext"
+		],
 		"experimentalDecorators": true,
 		"sourceMap": true,
 		"esModuleInterop": true,
 		"downlevelIteration": true,
 		"allowJs": true,
 		"outDir": "coverage/src",
+		"isolatedModules": true,
 		"strict": true,
 		"noImplicitAny": true,
 		"strictNullChecks": true,
@@ -24,17 +28,22 @@
 		"forceConsistentCasingInFileNames": true,
 		"baseUrl": ".",
 		"paths": {
-			"*": ["src/types/*"]
+			"*": [
+				"src/types/*"
+			]
 		},
 		"typeRoots": [
 			"./node_modules/@types",
 			"./src/types"
 		],
-		"types": ["jest", "node"]
+		"types": [
+			"jest",
+			"node"
+		]
 	},
 	"include": [
 		"src/**/*",
 		"tests/**/*",
 		"demo/**/*"
 	]
-}
+}

package/tsconfig.json

@@ -1,12 +1,12 @@
 {
 	"compilerOptions": {
-		"target": "es2018",
-		"module": "es2015",
+		"target": "es2020",
+		"module": "esnext",
 		"moduleResolution": "node",
 		"jsx": "react",
 		"jsxFactory": "app.h",
 		"jsxFragmentFactory": "app.Fragment",
-		"lib": ["dom", "es2018", "esnext.asynciterable"],
+		"lib": ["dom", "es2020", "esnext.asynciterable"],
 		"experimentalDecorators": true,
 		"sourceMap": true,
 		"esModuleInterop": true,

package/webpack.config.cjs

@@ -5,9 +5,11 @@ module.exports = {
   entry: {
     'dist/apprun': './src/apprun.ts',
     'dist/apprun-play': './src/apprun-play.tsx',
+    'dist/apprun-code': './src/apprun-code.tsx',
     'dist/apprun-html': './src/apprun-html.ts',
-    './jsx-runtime': './src/vdom.ts',
     'dist/apprun-dev-tools': './src/apprun-dev-tools.tsx',
+    'dist/createState': './src/createState.ts',
+    'jsx-runtime': './src/vdom.ts',
     'demo/app': './demo/main.ts'
   },
   output: {

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