apprun 3.38.0 → 6.0.0-rc.0

package/src/vdom-my.ts

@@ -1,286 +0,0 @@
-/** * 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);
-}
-
-function collect(children) {
-  const ch = [];
-  const push = (c) => {
-    if (c !== null && c !== undefined && c !== '' && c !== false) {
-      ch.push((typeof c === 'function' || typeof c === 'object') ? c : `${c}`);
-    }
-  }
-  children && children.forEach(c => {
-    if (Array.isArray(c)) {
-      c.forEach(i => push(i));
-    } else {
-      push(c);
-    }
-  });
-  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 };
-  else if (Array.isArray(tag)) return tag; // JSX fragments - babel
-  else if (tag === undefined && children) return ch; // JSX fragments - typescript
-  else if (Object.getPrototypeOf(tag).__isAppRunComponent) return { tag, props, children: ch } // createComponent(tag, { ...props, children });
-  else if (typeof tag === 'function') return tag(props, ch);
-  else throw new Error(`Unknown tag in vdom ${tag}`);
-};
-
-export const updateElement = (element: Element | string, nodes: VDOM, component = {}) => {
-  // tslint:disable-next-line
-  if (nodes == null || nodes === false) return;
-  const el = (typeof element === 'string' && element) ?
-    document.getElementById(element) || document.querySelector(element) : element;
-  nodes = directive(nodes, component);
-  render(el, nodes, component);
-}
-
-function render(element: Element, nodes: VDOM, parent = {}) {
-  // tslint:disable-next-line
-  if (nodes == null || nodes === false) return;
-  nodes = createComponent(nodes, parent);
-  if (!element) return;
-  const isSvg = element.nodeName === "SVG";
-  if (Array.isArray(nodes)) {
-    updateChildren(element, nodes, isSvg);
-  } else {
-    updateChildren(element, [nodes], isSvg);
-  }
-}
-
-function same(el: Element, node: VNode) {
-  // if (!el || !node) return false;
-  const key1 = el.nodeName;
-  const key2 = `${node.tag || ''}`;
-  return key1.toUpperCase() === key2.toUpperCase();
-}
-
-function update(element: Element, node: VNode, isSvg: boolean) {
-  // console.assert(!!element);
-  isSvg = isSvg || node.tag === "svg";
-  if (!same(element, node)) {
-    element.parentNode.replaceChild(create(node, isSvg), element);
-    return;
-  }
-  updateChildren(element, node.children, isSvg);
-  updateProps(element, node.props, isSvg);
-}
-
-function updateChildren(element, children, isSvg: boolean) {
-  const old_len = element.childNodes?.length || 0;
-  const new_len = children?.length || 0;
-  const len = Math.min(old_len, new_len);
-  for (let i = 0; i < len; i++) {
-    const child = children[i];
-    const el = element.childNodes[i];
-    if (typeof child === 'string') {
-      if (el.textContent !== child) {
-        if (el.nodeType === 3) {
-          el.nodeValue = child
-        } else {
-          element.replaceChild(createText(child), el);
-        }
-      }
-    } else if (child instanceof HTMLElement || child instanceof SVGElement) {
-      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);
-      }
-    }
-  }
-
-  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++) {
-      d.appendChild(create(children[i], isSvg));
-    }
-    element.appendChild(d);
-  }
-}
-
-export const safeHTML = (html: string) => {
-  const div = document.createElement('section');
-  div.insertAdjacentHTML('afterbegin', html)
-  return Array.from(div.children);
-}
-
-function createText(node) {
-  if (node?.indexOf('_html:') === 0) { // ?
-    const div = document.createElement('div');
-    div.insertAdjacentHTML('afterbegin', node.substring(6))
-    return div;
-  } else {
-    return document.createTextNode(node ?? '');
-  }
-}
-
-function create(node: VNode | string | HTMLElement | SVGElement, isSvg: boolean): Element {
-  // console.assert(node !== null && node !== undefined);
-  if ((node instanceof HTMLElement) || (node instanceof SVGElement)) return node;
-  if (typeof node === "string") return createText(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)
-    : document.createElement(node.tag);
-
-  updateProps(element, node.props, isSvg);
-  if (node.children) node.children.forEach(child => element.appendChild(create(child, isSvg)));
-
-  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;
-
-    // Lightweight cleanup - only when counter reaches threshold
-    if (++cleanupCounter >= CLEANUP_THRESHOLD) {
-      cleanupKeyCache();
-      cleanupCounter = 0;
-    }
-  }
-  return element
-}
-
-function render_component(node, parent, idx) {
-  const { tag, props, children } = node;
-  let key = `_${idx}`;
-  let id = props && props['id'];
-  if (!id) id = `_${idx}${Date.now()}`;
-  else key = id;
-  let asTag = 'section';
-  if (props && props['as']) {
-    asTag = props['as'];
-    delete props['as'];
-  }
-  if (!parent.__componentCache) parent.__componentCache = {};
-  let component = parent.__componentCache[key];
-  if (!component || !(component instanceof tag) || !component.element) {
-    const element = document.createElement(asTag);
-    component = parent.__componentCache[key] = new tag({ ...props, children }).mount(element, { render: true });
-  } else {
-    component.renderState(component.state);
-  }
-  if (component.mounted) {
-    const new_state = component.mounted(props, children, component.state);
-    (typeof new_state !== 'undefined') && component.setState(new_state);
-  }
-  updateProps(component.element, props, false);
-  return component.element;
-}
-
-function createComponent(node, parent, idx = 0) {
-  if (typeof node === 'string') return node;
-  if (Array.isArray(node)) return node.map(child => createComponent(child, parent, idx++));
-  let vdom = node;
-  if (node && typeof node.tag === 'function' && Object.getPrototypeOf(node.tag).__isAppRunComponent) {
-    vdom = render_component(node, parent, idx);
-  }
-  if (vdom && Array.isArray(vdom.children)) {
-    const new_parent = vdom.props?._component;
-    if (new_parent) {
-      let i = 0;
-      vdom.children = vdom.children.map(child => createComponent(child, new_parent, i++));
-    } else {
-      vdom.children = vdom.children.map(child => createComponent(child, parent, idx++));
-    }
-  }
-  return vdom;
-}

package/src/vdom-patch.ts

@@ -1,108 +0,0 @@
-enum CHANGES {
-  NO_ATTR_CHANGE = 1,
-  NO_TREE_CHANGE = 2,
-}
-
-export function patch(vdom1, vdom2) {
-  if (!vdom1?.length || !vdom2?.length) return;
-  const old_len = vdom1.length;
-  const new_len = vdom2.length;
-  const len = Math.min(old_len, new_len);
-  for (let i = 0; i < len; i++) {
-    const node1 = vdom1[i];
-    const node2 = vdom2[i];
-    if (!node2 || typeof node2 !== 'object') continue;
-    if (_areEquals(node1, node2)) {
-      node2._op = CHANGES.NO_ATTR_CHANGE | CHANGES.NO_TREE_CHANGE;
-    } else {
-      if (_areEquals(node1.props, node2.props)) {
-        node2._op = CHANGES.NO_ATTR_CHANGE;
-      }
-      if (_areEquals(node1.children, node2.children)) {
-        node2._op = node2._op | CHANGES.NO_TREE_CHANGE;
-      } else {
-        patch(node1.children, node2.children);
-      }
-    }
-  }
-}
-
-export function get_vdom(node: Node) {
-  if (!node) return null;
-  if (node.nodeType === 3) return node.nodeValue;
-  const children = [];
-  if (node.childNodes) {
-    for (let i = 0; i < node.childNodes.length; i++) {
-      children.push(get_vdom(node.childNodes[i]));
-    }
-  }
-  const tag = node['tagName'] ? node['tagName'].toLocaleLowerCase() : node;
-  return {
-    tag,
-    props: node['_props'],
-    children
-  }
-}
-
-// based on https://github.com/epoberezkin/fast-deep-equal
-// MIT License
-
-// Copyright (c) 2017 Evgeny Poberezkin
-
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-
-// The above copyright notice and this permission notice shall be included in all
-// copies or substantial portions of the Software.
-
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-// SOFTWARE.
-export function _areEquals(a: any, b: any): boolean {
-  if (a === b) return true;
-
-  if (a && b && typeof a == 'object' && typeof b == 'object') {
-    var arrA = Array.isArray(a)
-      , arrB = Array.isArray(b)
-      , i
-      , length
-      , key;
-
-    if (arrA && arrB) {
-      length = a.length;
-      if (length != b.length) return false;
-      for (i = length; i-- !== 0;)
-        if (!_areEquals(a[i], b[i])) return false;
-      return true;
-    }
-
-    if (arrA != arrB) return false;
-
-    var keys = Object.keys(a);
-    length = keys.length;
-
-    if (length !== Object.keys(b).length)
-      return false;
-
-    for (i = length; i-- !== 0;)
-      if (!b.hasOwnProperty(keys[i])) return false;
-
-    for (i = length; i-- !== 0;) {
-      key = keys[i];
-      if (!_areEquals(a[key], b[key])) return false;
-    }
-
-    return true;
-  }
-
-  return a!==a && b!==b;
-};
-export default patch;

package/src/vdom-to-html.tsx

@@ -1,49 +0,0 @@
-
-import { VDOM } from './types';
-import { TemplateResult } from 'lit-html';
-
-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 clean(obj) {
-  for (var i in obj) {
-    if (obj[i] == null) {
-      delete obj[i];
-    } else if (typeof obj[i] === 'object') {
-      clean(obj[i]);
-    }
-  }
-}
-
-function toHTML (vdom) {
-  if (!vdom) return '';
-  if (vdom['_$litType$']) {
-    return vdom.toString();
-  }
-  clean(vdom);
-  if (Array.isArray(vdom)) return toHTMLArray(vdom);
-  if (typeof vdom === 'string') {
-    return vdom.startsWith('_html:') ? vdom.substring(6) : vdom;
-  } else 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);
-}
-
-export default toHTML;

package/src/vdom.ts

@@ -1,28 +0,0 @@
-/**
- * Virtual DOM Implementation
- * 
- * This file provides the core virtual DOM functionality:
- * 1. createElement: Creates virtual DOM nodes
- * 2. Fragment: Support for fragments
- * 3. render: Renders virtual DOM to real DOM
- * 4. safeHTML: Safely renders HTML strings
- * 
- * The virtual DOM system:
- * - Provides efficient DOM updates
- * - Supports JSX compilation
- * - Handles component rendering
- * - Manages DOM diffing and patching
- * 
- * Usage:
- * ```ts
- * // JSX gets compiled to createElement calls
- * const vdom = <div id="app">Hello</div>;
- * 
- * // Render to DOM
- * render(document.body, vdom);
- * ```
- */
-
-import { createElement, updateElement, Fragment, safeHTML } from './vdom-my';
-export { createElement, Fragment, updateElement as render, safeHTML };
-export { createElement as jsx, createElement as jsxs };

package/src/version.ts

@@ -1,16 +0,0 @@
-/**
- * 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.38.0';
-
-// Version string with prefix for global tracking
-export const APPRUN_VERSION_GLOBAL = `AppRun-${APPRUN_VERSION}`;

package/src/web-component.ts

@@ -1,154 +0,0 @@
-/**
- * Web Components Integration
- * 
- * This file enables using AppRun components as Web Components:
- * 1. Custom Element Creation
- *    - Converts AppRun components to custom elements
- *    - 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 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 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', { 
- *   shadow: true,
- *   observedAttributes: ['name', 'value']
- * })
- * class MyComponent extends Component {
- *   // Regular AppRun component code
- * }
- * 
- * // Use in HTML
- * <my-element name="value" data-prop="complex"></my-element>
- * ```
- */
-
-declare var customElements;
-
-import { CustomElementOptions } from './types';
-
-export const customElement = (componentClass, options: CustomElementOptions = {}) => class CustomElement extends HTMLElement {
-  public _shadowRoot;
-  public _component;
-  public _attrMap: (arg0: string) => string;
-  public on;
-  public run;
-  constructor() {
-    super();
-  }
-  get component() { return this._component; }
-  get state() { return this._component.state; }
-
-  static get observedAttributes() {
-    // attributes need to be set to lowercase in order to get observed
-    return (options.observedAttributes || []).map(attr => attr.toLowerCase());
-  }
-
-  connectedCallback() {
-    if (this.isConnected && !this._component) {
-      const opts = options || {};
-      this._shadowRoot = opts.shadow ? this.attachShadow({ mode: 'open' }) : this;
-      const observedAttributes = (opts.observedAttributes || [])
-
-      const attrMap = observedAttributes.reduce((map, name) => {
-        const lc = name.toLowerCase()
-        if (lc !== name) {
-          map[lc] = name
-        }
-        return map
-      }, {})
-      this._attrMap = (name: string): string => attrMap[name] || name
-
-      const props = {};
-      Array.from(this.attributes).forEach(item => props[this._attrMap(item.name)] = item.value);
-
-      // add getters/ setters to allow observation on observedAttributes
-      observedAttributes.forEach(name => {
-        if (this[name] !== undefined) props[name] = this[name];
-        Object.defineProperty(this, name, {
-          get(): any {
-            return props[name];
-          },
-          set(this: CustomElement, value: unknown) {
-            // trigger change event
-            this.attributeChangedCallback(name, props[name], value)
-          },
-          configurable: true,
-          enumerable: true
-        });
-      })
-
-      requestAnimationFrame(() => {
-        const children = this.children ? Array.from(this.children) : [];
-        // children.forEach(el => el.parentElement.removeChild(el));
-        this._component = new componentClass({ ...props, children }).mount(this._shadowRoot, opts);
-        // attach props to component
-        this._component._props = props;
-        // expose dispatchEvent
-        this._component.dispatchEvent = this.dispatchEvent.bind(this)
-        if (this._component.mounted) {
-          const new_state = this._component.mounted(props, children, this._component.state);
-          if (typeof new_state !== 'undefined') this._component.state = new_state;
-        }
-        this.on = this._component.on.bind(this._component);
-        this.run = this._component.run.bind(this._component);
-        if (!(opts.render === false)) this._component.run('.');
-      });
-    }
-  }
-
-  disconnectedCallback() {
-    this._component?.unload?.();
-    this._component?.unmount?.();
-    this._component = null;
-  }
-
-  attributeChangedCallback(name: string, oldValue: unknown, value: unknown) {
-    if (this._component) {
-      // camelCase attributes arrive only in lowercase
-      const mappedName = this._attrMap(name);
-      // store the new property/ attribute
-      this._component._props[mappedName] = value;
-      this._component.run('attributeChanged', mappedName, oldValue, value);
-
-      if (value !== oldValue && !(options.render === false)) {
-        window.requestAnimationFrame(() => {
-          // re-render state with new combined props on next animation frame
-          this._component.run('.')
-        })
-      }
-    }
-  }
-}
-
-export default (name: string, componentClass, options?: CustomElementOptions) => {
-  (typeof customElements !== 'undefined') && customElements.define(name, customElement(componentClass, options))
-}

package/tsconfig.jest.json

@@ -1,49 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "es2020",
-		"module": "esnext",
-		"moduleResolution": "node",
-		"jsx": "react",
-		"reactNamespace": "app",
-		"lib": [
-			"dom",
-			"esnext"
-		],
-		"experimentalDecorators": true,
-		"sourceMap": true,
-		"esModuleInterop": true,
-		"downlevelIteration": true,
-		"allowJs": true,
-		"outDir": "coverage/src",
-		"isolatedModules": true,
-		"strict": true,
-		"noImplicitAny": true,
-		"strictNullChecks": true,
-		"strictFunctionTypes": true,
-		"strictBindCallApply": true,
-		"strictPropertyInitialization": true,
-		"noImplicitThis": true,
-		"alwaysStrict": true,
-		"skipLibCheck": true,
-		"forceConsistentCasingInFileNames": true,
-		"baseUrl": ".",
-		"paths": {
-			"*": [
-				"src/types/*"
-			]
-		},
-		"typeRoots": [
-			"./node_modules/@types",
-			"./src/types"
-		],
-		"types": [
-			"jest",
-			"node"
-		]
-	},
-	"include": [
-		"src/**/*",
-		"tests/**/*",
-		"demo/**/*"
-	]
-}