apprun 3.33.9 → 3.35.0

package/src/app.ts

@@ -1,28 +1,60 @@
-import { EventOptions} from './types'
+/**
+ * Core AppRun application class and singleton instance
+ *
+ * This file provides:
+ * 1. App class - The core event system implementation with pub/sub capabilities
+ *    - on(): Subscribe to events
+ *    - off(): Unsubscribe from events
+ *    - run(): Publish events synchronously
+ *    - runAsync(): Publish events asynchronously
+ *    - query(): Alias for runAsync
+ *
+ * 2. Default app singleton - Global event bus instance
+ *    - Created once and reused across the application
+ *    - Stored in global scope (window/global)
+ *    - Version tracked to prevent duplicate instances
+ *
+ * Usage:
+ * ```ts
+ * // Subscribe to events
+ * app.on('event-name', (state, ...args) => {
+ *   // Handle event
+ * });
+ *
+ * // Publish events
+ * app.run('event-name', ...args);
+ * ```
+ */
+
+import { EventOptions } from './types'
+
 export class App {
 
-  _events: Object;
+  _events: { [key: string]: Array<{ fn: (...args: any[]) => any, options: EventOptions }> };
+
+  public start: any;
+  public h: any;
+  public createElement: any;
+  public render: any;
+  public Fragment: any;
+  public webComponent: any;
+  public safeHTML: any;
+  public use_render: any;
+  public use_react: any;
+  public route: any;
 
-  public start;
-  public h;
-  public createElement;
-  public render;
-  public Fragment;
-  public webComponent;
-  public safeHTML;
-  public use_render;
-  public use_react;
+  public version: string;
 
   constructor() {
-    this._events = {};
+    this._events = {} as { [key: string]: Array<{ fn: (...args: any[]) => any, options: EventOptions }> };
   }
 
-  on(name: string, fn: (...args) => void, options: EventOptions = {}): void {
+  on(name: string, fn: (...args: any[]) => any, options: EventOptions = {}): void {
     this._events[name] = this._events[name] || [];
     this._events[name].push({ fn, options });
   }
 
-  off(name: string, fn: (...args) => void): void {
+  off(name: string, fn: (...args: any[]) => any): void {
     const subscribers = this._events[name] || [];
 
     this._events[name] = subscribers.filter((sub) => sub.fn !== fn);
@@ -32,7 +64,7 @@ export class App {
     return this._events[name];
   }
 
-  run(name: string, ...args): number {
+  run(name: string, ...args: any[]): number {
     const subscribers = this.getSubscribers(name, this._events);
     console.assert(subscribers && subscribers.length > 0, 'No subscriber for event: ' + name);
     subscribers.forEach((sub) => {
@@ -48,11 +80,11 @@ export class App {
     return subscribers.length;
   }
 
-  once(name: string, fn, options: EventOptions = {}): void {
+  once(name: string, fn: (...args: any[]) => any, options: EventOptions = {}): void {
     this.on(name, fn, { ...options, once: true });
   }
 
-  private delay(name, fn, args, options): void {
+  private delay(name: string, fn: (...args: any[]) => any, args: any[], options: EventOptions): void {
     if (options._t) clearTimeout(options._t);
     options._t = setTimeout(() => {
       clearTimeout(options._t);
@@ -60,7 +92,7 @@ export class App {
     }, options.delay);
   }
 
-  runAsync(name: string, ...args): Promise<any[]> {
+  runAsync(name: string, ...args: any[]): Promise<any[]> {
     const subscribers = this.getSubscribers(name, this._events);
     console.assert(subscribers && subscribers.length > 0, 'No subscriber for event: ' + name);
     const promises = subscribers.map(sub => {
@@ -70,11 +102,11 @@ export class App {
     return Promise.all(promises);
   }
 
-  query(name: string, ...args): Promise<any[]> {
+  query(name: string, ...args: any[]): Promise<any[]> {
     return this.runAsync(name, ...args);
   }
 
-  private getSubscribers(name: string, events) {
+  private getSubscribers(name: string, events: { [key: string]: Array<{ fn: (...args: any[]) => any, options: EventOptions }> }): Array<{ fn: (...args: any[]) => any, options: EventOptions }> {
     const subscribers = events[name] || [];
 
     // Update the list of subscribers by pulling out those which will run once.
@@ -93,15 +125,17 @@ export class App {
   }
 }
 
-const AppRunVersions = 'AppRun-3';
-let app: App;
-const root = (typeof self === 'object' && self.self === self && self) ||
-  (typeof global === 'object' && global.global === global && global)
-if (root['app'] && root['_AppRunVersions']) {
-  app = root['app'];
+const AppRunVersions = 'AppRun-3.3.11';
+let _app: App;
+const root = (typeof window !== 'undefined' ? window :
+  typeof global !== 'undefined' ? global :
+    typeof self !== 'undefined' ? self : {}) as any;
+
+if (root.app && root._AppRunVersions) {
+  _app = root.app;
 } else {
-  app = new App();
-  root['app'] = app;
-  root['_AppRunVersions'] = AppRunVersions;
+  _app = new App();
+  root.app = _app;
+  root._AppRunVersions = AppRunVersions;
 }
-export default app;
+export default _app;

package/src/apprun.ts

@@ -1,3 +1,37 @@
+/**
+ * Main AppRun framework entry point
+ *
+ * This file:
+ * 1. Assembles core AppRun modules into a complete framework
+ * 2. Exports public API and types
+ * 3. Initializes global app instance with:
+ *    - Virtual DOM rendering
+ *    - Component system
+ *    - Router
+ *    - Web component support
+ *
+ * Key exports:
+ * - app: Global event system instance
+ * - Component: Base component class
+ * - Decorators: @on, @update, @customElement
+ * - Router events and configuration
+ * - Web component registration
+ *
+ * Usage:
+ * ```ts
+ * import { app, Component } from 'apprun';
+ *
+ * // Create components
+ * class MyComponent extends Component {
+ *   state = // Initial state
+ *   view = state => // Render view
+ *   update = {
+ *     'event': (state, ...args) => // Handle events
+ *   }
+ * }
+ * ```
+ */
+
 import app, { App } from './app';
 import { createElement, render, Fragment, safeHTML } from './vdom';
 import { Component } from './component';
@@ -7,7 +41,26 @@ import webComponent, { CustomElementOptions } from './web-component';
 import { Route, route, ROUTER_EVENT, ROUTER_404_EVENT } from './router';
 
 export type StatelessComponent<T = {}> = (args: T) => string | VNode | void;
-export { App, app, Component, View, Action, Update, on, update, EventOptions, ActionOptions, MountOptions, Fragment, safeHTML }
+type OnDecorator = {
+  <T = any>(options?: any): (constructor: Function) => void;
+  <E = string>(events?: E, options?: any): (target: any, key: string) => void;
+};
+
+export {
+  App,
+  app,
+  Component,
+  View,
+  Action,
+  Update,
+  on,
+  update,
+  EventOptions,
+  ActionOptions,
+  MountOptions,
+  Fragment,
+  safeHTML
+}
 export { update as event };
 export { ROUTER_EVENT, ROUTER_404_EVENT };
 export { customElement, CustomElementOptions, AppStartOptions };
@@ -32,6 +85,9 @@ export interface IApp {
 }
 
 if (!app.start) {
+
+  app.version = '3.35.0';
+
   app.h = app.createElement = createElement;
   app.render = render;
   app.Fragment = Fragment;
@@ -49,35 +105,60 @@ if (!app.start) {
   };
 
   const NOOP = _ => {/* Intentionally empty */ }
-  app.on('$', NOOP);
+  // app.on('$', NOOP);
   app.on('debug', _ => NOOP);
   app.on(ROUTER_EVENT, NOOP);
-  app.on('#', NOOP);
-  app['route'] = route;
+  app.on(ROUTER_404_EVENT, NOOP);
+  app.route = route;
   app.on('route', url => app['route'] && app['route'](url));
 
   if (typeof document === 'object') {
     document.addEventListener("DOMContentLoaded", () => {
-      if (app['route'] === route) {
-        window.onpopstate = () => route(location.hash);
-        document.body.hasAttribute('apprun-no-init') || app['no-init-route'] || route(location.hash);
+      const init_load = document.body.hasAttribute('apprun-no-init') || app['no-init-route'] || false;
+      const use_hash = app.find('#') || app.find('#/') || false;
+
+      // console.log(`AppRun ${app.version} started with ${use_hash ? 'hash' : 'path'} routing. Initial load: ${init_load ? 'disabled' : 'enabled'}.`);
+      window.addEventListener('hashchange', () => route(location.hash));
+      window.addEventListener('popstate', () => route(location.pathname));
+
+      if (use_hash) {
+        init_load && route(location.hash);
+      } else {
+        init_load && route(location.pathname);
+        document.body.addEventListener('click', e => {
+          const element = e.target as HTMLElement;
+          const menu = (element.tagName === 'A' ? element : element.closest('a')) as HTMLAnchorElement;
+          if (menu &&
+            menu.origin === location.origin) {
+            e.preventDefault();
+            history.pushState(null, '', menu.pathname);
+            route(menu.pathname);
+          }
+        });
       }
     });
   }
 
+  type ComponentType = typeof Component & {
+    <T = any>(options?: any): (constructor: Function) => void;
+  };
+
   if (typeof window === 'object') {
-    window['Component'] = Component;
+    window['Component'] = Component as ComponentType;
     window['_React'] = window['React'];
     window['React'] = app;
-    window['on'] = on;
+    window['on'] = on as OnDecorator;
     window['customElement'] = customElement;
     window['safeHTML'] = safeHTML;
   }
 
-  app.use_render = (render, mode = 0) =>
-    mode === 0 ?
-      app.render = (el, vdom) => render(vdom, el) : // react style
-      app.render = (el, vdom) => render(el, vdom);  // apprun style
+  app.use_render = (render, mode = 0) => {
+    if (mode === 0) {
+      app.render = (el, vdom) => render(vdom, el); // react style
+    } else {
+      app.render = (el, vdom) => render(el, vdom); // apprun style
+    }
+  };
 
   app.use_react = (React, ReactDOM) => {
     app.h = app.createElement = React.createElement;

package/src/component.ts

@@ -1,3 +1,36 @@
+/**
+ * AppRun Component System Implementation
+ *
+ * This file provides the Component class which is the foundation for:
+ * 1. State Management
+ *    - Maintains component state
+ *    - Handles state updates
+ *    - Supports state history
+ *
+ * 2. View Rendering
+ *    - Renders virtual DOM to real DOM
+ *    - Handles component lifecycle (mounted, rendered, unload)
+ *    - Supports shadow DOM and web components
+ *
+ * 3. Event Handling
+ *    - Local and global event subscription
+ *    - Event handler registration via decorators
+ *    - Action to state updates
+ *
+ * Usage:
+ * ```ts
+ * class MyComponent extends Component {
+ *   state = // Initial state
+ *   view = state => // Return virtual DOM
+ *   update = {
+ *     'event': (state, ...args) => // Return new state
+ *   }
+ * }
+ *
+ * // Mount component
+ * new MyComponent().mount('element-id');
+ * ```
+ */
 
 import app, { App } from './app';
 import { Reflect } from './decorator'
@@ -79,7 +112,30 @@ export class Component<T = any, E = any> {
 
   public setState(state: T, options: ActionOptions & EventOptions
     = { render: true, history: false }) {
-    if (state instanceof Promise) {
+
+    const handleAsyncIterator = async (iterator: AsyncIterator<T>) => {
+      try {
+        while (true) {
+          const { value, done } = await iterator.next();
+          if (done) break;
+          this.setState(value, options);
+        }
+      } catch (e) {
+        console.error('Error in async iterator:', e);
+      }
+    };
+
+    const result = state as any;
+    if (result?.[Symbol.asyncIterator]) {
+      // handleAsyncIterator(result[Symbol.asyncIterator]());
+      this.setState(handleAsyncIterator(result[Symbol.asyncIterator]()) as any, options);
+      return;
+    } else if (result?.[Symbol.iterator] && typeof result.next === "function") {
+      for (const value of result) {
+        this.setState(value, options);
+      }
+      return;
+    } else if (state && state instanceof Promise) {
       // Promise will not be saved or rendered
       // state will be saved and rendered when promise is resolved
       Promise.resolve(state).then(v => {

package/src/decorator.ts

@@ -1,5 +1,39 @@
 import webComponent, { CustomElementOptions } from './web-component';
 
+/**
+ * TypeScript Decorators for AppRun Components
+ * 
+ * This file provides decorators that enable:
+ * 1. Event Handler Registration
+ *    - @on(): Subscribe to events with options
+ *    - @update(): Define state updates with metadata
+ * 
+ * 2. Web Component Integration
+ *    - @customElement(): Register as custom element with options
+ *    - Handles shadow DOM and attribute observation
+ * 
+ * 3. Metadata Management
+ *    - Custom Reflect implementation for decorator metadata
+ *    - Stores event handler and update metadata
+ *    - Supports runtime reflection for dynamic behavior
+ * 
+ * Usage:
+ * ```ts
+ * @customElement('my-element')
+ * class MyComponent extends Component {
+ *   @on('event')  
+ *   handler(state, ...args) {
+ *     // Handle event
+ *   }
+ * 
+ *   @update('event') 
+ *   updater(state, ...args) {
+ *     // Update state
+ *   }
+ * }
+ * ```
+ */
+
 // tslint:disable:no-invalid-this
 export const Reflect = {
 
@@ -44,4 +78,3 @@ export function customElement(name: string, options?: CustomElementOptions) {
     return constructor;
   }
 }
-

package/src/directive.ts

@@ -1,3 +1,35 @@
+/**
+ * Component Directives Implementation
+ * 
+ * This file provides built-in directives for components:
+ * 1. Event Binding
+ *    - $on: Bind DOM events to component events
+ *    - Supports event delegation and parameters
+ *    - Handles function, string, and array event handlers
+ * 
+ * 2. Two-way Data Binding
+ *    - $bind: Sync form elements with component state
+ *    - Handles input types: text, checkbox, radio, select
+ *    - Automatic value type conversion
+ *    - Support for complex property paths
+ * 
+ * 3. Custom Directives
+ *    - Extensible directive system
+ *    - Processes virtual DOM during rendering
+ *    - Supports custom attribute directives
+ * 
+ * Usage:
+ * ```tsx
+ * // Event binding
+ * <button $onclick="event-name">Click</button>
+ * <input $oninput={e => setState(e.target.value)} />
+ * 
+ * // Two-way binding
+ * <input $bind="state.property" />
+ * <select $bind="selected">...</select>
+ * ```
+ */
+
 import app from './app';
 
 const getStateValue = (component, name) => {
@@ -92,4 +124,4 @@ const directive = (vdom, component) => {
   }
 }
 
-export default directive;
+export default directive;

package/src/global.d.ts

@@ -0,0 +1,22 @@
+import { App } from './app';
+import { Component } from './component';
+
+declare global {
+  var app: App;
+  var _AppRunVersions: string;
+  interface Window {
+    app: App;
+    _AppRunVersions: string;
+    Component: typeof Component & {
+      <T = any>(options?: any): (constructor: Function) => void;
+    };
+    _React: any;
+    React: App;
+    on: {
+      <T = any>(options?: any): (constructor: Function) => void;
+      <E = string>(events?: E, options?: any): (target: any, key: string) => void;
+    };
+    customElement: (name: string) => (constructor: Function) => void;
+    safeHTML: (html: string) => any[];
+  }
+}

package/src/router.ts

@@ -1,11 +1,37 @@
+/**
+ * AppRun Router Implementation
+ * 
+ * This file provides URL routing capabilities:
+ * 1. Hash-based routing (#/path)
+ * 2. Path-based routing (/path) 
+ * 3. Event-based navigation
+ * 
+ * Features:
+ * - Automatic route event firing
+ * - 404 handling via ROUTER_404_EVENT
+ * - History API integration
+ * - Route parameter parsing
+ * 
+ * Usage:
+ * ```ts
+ * // Handle routes
+ * app.on('#/home', () => // Show home page);
+ * app.on('#/users/:id', (id) => // Show user profile);
+ * 
+ * // Navigate programmatically
+ * app.run('route', '#/home');
+ * ```
+ */
+
 import app from './app';
 
 export type Route = (url: string, ...args: any[]) => any;
 
 export const ROUTER_EVENT: string = '//';
 export const ROUTER_404_EVENT: string = '///';
-
 export const route: Route = (url: string) => {
+  if (app['lastUrl'] === url) return; // Prevent duplicate routing
+  app['lastUrl'] = url;
   if (!url) url = '#';
   if (url.startsWith('#')) {
     const [name, ...rest] = url.split('/');
@@ -20,4 +46,4 @@ export const route: Route = (url: string) => {
     app.run(ROUTER_EVENT, url);
   }
 }
-export default route;
+export default route;

package/src/types/apprun.d.ts

@@ -0,0 +1,56 @@
+declare type VNode = {
+  tag: string;
+  props?: Record<string, any>;
+  children?: Array<VNode | string | number>;
+} | string | number;
+
+declare type VDOM = VNode | VNode[];
+
+declare type View<T = any> = (state: T) => VDOM | void;
+declare type Action<T = any> = (state: T, ...p: any[]) => T | void | Promise<T>;
+declare type ActionDef<T = any> = [Action<T>, object?];
+declare type Update<T = any> = { [name: string]: Action<T> | ActionDef<T> | Array<Action<T> | ActionDef<T>> };
+
+declare interface IApp {
+  start<T>(element?: Element | string | null, model?: T, view?: View<T>, update?: Update<T>, options?: AppStartOptions): Component<T>;
+  on(name: string, fn: (...args: any[]) => void, options?: any): void;
+  run(name: string, ...args: any[]): void;
+  createElement(tag: string | Function, props?: any, ...children: any[]): VNode;
+  render(element: Element, node: VNode): void;
+}
+
+declare interface Component<T = any> {
+  readonly state: T;
+  setState(state: T, options?: any): void;
+  mount(element?: Element | string | null, options?: any): Component<T>;
+  start(element?: Element | string | null, options?: any): Component<T>;
+  run(name: string, ...args: any[]): void;
+  rendered?: (state: T) => void;
+  view?: View<T>;
+  update?: Update<T>;
+  element?: Element;
+}
+
+declare interface CustomElementOptions {
+  render?: boolean;
+  shadow?: boolean;
+  history?: boolean | { prev: string; next: string };
+  global_event?: boolean;
+  route?: string;
+}
+
+declare interface AppStartOptions extends CustomElementOptions {
+  render?: boolean;
+  history?: boolean | { prev: string; next: string };
+  global_event?: boolean;
+  route?: string;
+}
+
+declare interface Route {
+  (url: string): void;
+  push(url: string, notify?: boolean): void;
+}
+
+declare const app: IApp;
+declare function on<T = any>(name?: string, options?: any): (target: any, key: string) => void;
+declare function Component<T = any>(options?: any): (constructor: Function) => void;

package/src/types.ts

@@ -1,3 +1,32 @@
+/**
+ * Core TypeScript Type Definitions
+ * 
+ * This file defines the fundamental types used across AppRun:
+ * 1. Component Types
+ *    - View: Function that renders state to VDOM
+ *    - Action: Function that updates state
+ *    - Update: Collection of actions
+ * 
+ * 2. Virtual DOM Types
+ *    - VNode: Virtual DOM node structure
+ *    - VDOM: Union of possible VDOM types
+ *    - Element: DOM element references
+ * 
+ * 3. Configuration Types
+ *    - EventOptions: Event handler options (once, delay, etc)
+ *    - ActionOptions: Action behavior options (render, history, etc)
+ *    - MountOptions: Component mounting options (global events, routing)
+ *    - AppStartOptions: Application startup configuration
+ * 
+ * Usage:
+ * ```ts
+ * class MyComponent implements Component<State> {
+ *   view: View<State>;
+ *   update: Update<State>;
+ * }
+ * ```
+ */
+
 import { TemplateResult } from 'lit-html';
 export type Element = HTMLElement | string;
 export type VNode = {
@@ -31,4 +60,4 @@ export type AppStartOptions<T> = {
   route?: string;
   rendered?: (state: T) => void
   mounted?: (props:any, children:any, state: T) => T
-};
+};

package/src/vdom-lit-html.ts

@@ -1,9 +1,9 @@
 import { createElement, updateElement, Fragment } from './vdom-my';
 
 
-import { render, svg, html, noChange, nothing } from 'lit-html';
-import { directive, Directive, Part, PartInfo, PartType, EventPart } from 'lit-html/directive.js';
-import { unsafeHTML } from 'lit-html/directives/unsafe-html.js';
+import { render, svg, html, noChange, nothing } from 'lit';
+import { directive, Directive, PartInfo, ElementPart, DirectiveResult, EventPart, PartType } from 'lit/directive.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 import app from './apprun';
 
 function _render(element, vdom, parent?) {
@@ -26,32 +26,35 @@ export class RunDirective extends Directive {
   constructor(partInfo: PartInfo) {
     super(partInfo);
     // When necessary, validate part in constructor using `part.type`
-    if (partInfo.type !== PartType.EVENT) {
-      throw new Error('${run} can only be used in event handlers');
+    if (partInfo.type !== PartType.EVENT) { // In lit v3, use PartType.EVENT
+      throw new Error('run() can only be used in event handlers');
     }
   }
-  // Optional: override update to perform any direct DOM manipulation
-  update(part: Part, params) {
+  // Override update to perform any direct DOM manipulation
+  update(part: EventPart, props: Array<any>): DirectiveResult {
     /* Any imperative updates to DOM/parts would go here */
-
-    let { element, name } = part as EventPart;
+    const element = part.element;
+    const name = part.name;
+    const [eventOrFn, ...args] = props;
+    
     const getComponent = () => {
-      let component = element['_component'];
-      while (!component && element) {
-        element = element.parentElement;
-        component = element && element['_component'];
+      let el = element;
+      let component = el['_component'];
+      while (!component && el) {
+        el = el.parentElement;
+        component = el && el['_component'];
       }
       console.assert(!!component, 'Component not found.');
       return component;
     }
-    const [event, ...args] = params;
-    if (typeof event === 'string') {
+
+    if (typeof eventOrFn === 'string') {
       element[`on${name}`] = e => {
         const component = getComponent();
-        component ? component.run(event, ...args, e) : app.run(event, ...args, e)
+        component ? component.run(eventOrFn, ...args, e) : app.run(eventOrFn, ...args, e)
       }
-    } else if (typeof event === 'function') {
-      element[`on${name}`] = e => getComponent().setState(event(getComponent().state, ...args, e));
+    } else if (typeof eventOrFn === 'function') {
+      element[`on${name}`] = e => getComponent().setState(eventOrFn(getComponent().state, ...args, e));
     }
     return this.render();
   }
@@ -62,4 +65,3 @@ export class RunDirective extends Directive {
 
 const run = directive(RunDirective) as any;
 export { createElement, Fragment, html, svg, _render as render, run };
-