apprun 3.33.8 → 3.33.10

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 };
@@ -65,19 +118,26 @@ if (!app.start) {
     });
   }
 
+  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;
@@ -91,4 +151,19 @@ if (!app.start) {
       }
     }
   }
+
+  app.use_prettyLink = () => {
+    window.onload = () => app.route(location.pathname);
+    window.addEventListener("popstate", () => app.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);
+        app.route(menu.pathname);
+      }
+    });
+  }
 }

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,3 +1,28 @@
+/**
+ * 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;
@@ -20,4 +45,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 };
-

package/src/vdom.ts

@@ -1,4 +1,28 @@
+/**
+ * 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/web-component.ts

@@ -1,3 +1,36 @@
+/**
+ * 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, etc)
+ *    - Manages shadow DOM and light DOM rendering
+ * 
+ * 2. Property/Attribute Sync
+ *    - Observes attribute changes
+ *    - Updates component state automatically
+ *    - Handles camelCase/kebab-case conversion
+ *    - Supports complex property types
+ * 
+ * 3. Event Handling
+ *    - Proxies events between component and element
+ *    - Supports both global and local events
+ *    - Maintains proper event bubbling
+ * 
+ * Usage:
+ * ```ts
+ * // Register web component
+ * @customElement('my-element')
+ * class MyComponent extends Component {
+ *   // Regular AppRun component code
+ * }
+ * 
+ * // Use in HTML
+ * <my-element name="value"></my-element>
+ * ```
+ */
+
 declare var customElements;
 
 export type CustomElementOptions = {

package/tsconfig.jest.json

@@ -11,6 +11,30 @@
 		"esModuleInterop": true,
 		"downlevelIteration": true,
 		"allowJs": true,
-		"outDir": "coverage/src"
-	}
-}
+		"outDir": "coverage/src",
+		"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/**/*"
+	]
+}

package/tsconfig.json

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

package/webpack.config.cjs

@@ -1,10 +1,12 @@
 const path = require('path');
+const webpack = require('webpack');
 
 module.exports = {
   entry: {
     'dist/apprun': './src/apprun.ts',
     'dist/apprun-play': './src/apprun-play.tsx',
     'dist/apprun-html': './src/apprun-html.ts',
+    './jsx-runtime': './src/vdom.ts',
     'dist/apprun-dev-tools': './src/apprun-dev-tools.tsx',
     'demo/app': './demo/main.ts'
   },
@@ -27,5 +29,11 @@ module.exports = {
     open: true,
     static: path.join(__dirname),
   },
-  devtool: 'source-map'
-}
+  devtool: 'source-map',
+  plugins: [
+    new webpack.DefinePlugin({
+      // This tells Lit to run in production mode
+      'globalThis.DEV_MODE': JSON.stringify(false)
+    })
+  ]
+}