x4js 2.0.28 → 2.0.31

package/src/core/core_application.ts

@@ -17,7 +17,7 @@
 import { Component, componentFromDOM } from './component';
 import { CoreElement } from './core_element';
 import { CoreEvent, EventMap } from './core_events';
-import { getFocusableElements, ITabHandler } from './core_tools';
+import { asap, getFocusableElements, ITabHandler } from './core_tools';
 
 const socket_sent = Symbol( 'socket' );
 
@@ -32,10 +32,12 @@ export interface ApplicationEvents extends EventMap {
 	message: EvMessage;
 }
 
-// signleton
+// singleton
 let main_app: Application = null;
 
-
+/**
+ * Provides information about the user's device and browser capabilities.
+ */
 
 class Process {
 
@@ -49,61 +51,131 @@ class Process {
 	}
 }
 
+/**
+ * 
+ */
 
+interface AppProps {
+	/** The CSS selector for the DOM element where the application's main view will be mounted (default: `'body'`). */
+	mountPoint?: string;
+}
+
+/**
+ * The main application class, acting as a singleton.
+ * It manages the main view, environment variables, keyboard navigation,
+ * and provides utilities for local storage and WebSocket communication.
+ *
+ * Assertions ensure only one instance of `Application` can exist.
+ */
 
 export class Application<E extends ApplicationEvents = ApplicationEvents> extends CoreElement<E> {
 
 	private env = new Map<string,any>( );
 	private mainview: Component;
+	private props: AppProps;
+	private mounted = false;
 	
+	 /**
+     * Provides access to process-related information, such as touch capabilities.
+     */
+
 	static readonly process = new Process( );
 
-	constructor( ) {
+	/**
+     * Creates an instance of the Application.
+     * This class is a singleton; an assertion will fail if multiple instances are created.
+     * @param props - Configuration properties for the application.
+     */
+
+	constructor( props: AppProps = {} ) {
 		super( );
 
 		console.assert( main_app==null, "Application must be a singleton." );
 		// eslint-disable-next-line @typescript-eslint/no-this-alias
 		main_app = this;
+
+		const loaded = ( ) => {
+			this.mount( props.mountPoint ?? 'body' )
+		}
+
+		if( document.readyState=='complete' ) {
+			asap( loaded );
+		}
+		else {
+			window.addEventListener( "load", loaded, { once: true } );
+		}
 	}
 
+	/**
+	 * 
+	 */
+
+	private mount( mountPoint = 'body' ) {
+		if( !this.mounted && this.mainview ) {
+			const ev = document.querySelector( mountPoint );
+			if( ev ) {
+				ev.appendChild( this.mainview.dom );
+			}
+		}
+	}
+
+	/**
+     * Sets the main view component for the application.
+     * This component will be mounted to the DOM.
+     * @param view - The component to set as the main view.
+     */
+	
 	setMainView( view: Component ) {
 		this.mainview = view;
-		document.body.appendChild( view.dom );
 		this._setupKeyboard( );
 	}
 
+	/**
+     * Returns the singleton instance of the Application.
+     * @returns The application instance.
+     */
+
 	static instance<P extends Application = Application>( ): P {
 		return main_app as P;
 	}
 
-	/**
-	 * 
-	 */
+	 /**
+     * Retrieves the main view component of the application.
+     * @returns The application's main view component.
+     */
 
 	getMainView( ) {
 		return this.mainview;
 	}
 
 	/**
-	 * 
-	 */
+     * Sets an environment variable in the application's environment map.
+     * @param name - The name of the environment variable.
+     * @param value - The value to store for the environment variable.
+     */
 
 	setEnv( name: string, value: any ) {
 		this.env.set( name, value );
 	}
 
 	/**
-	 * 
-	 */
+     * Retrieves an environment variable from the application's environment map.
+     * @param name - The name of the environment variable.
+     * @param def_value - An optional default value to return if the variable is not found.
+     * @returns The value of the environment variable, or `def_value` if not found.
+     */
 	
 	getEnv( name: string, def_value?: any ) {
 		return this.env.get( name ) ?? def_value;
 	}
 
 	/**
-	 * small shortcut for Application.instance().fire( "global", ... );
-	 */
-	
+     * Retrieves an environment variable from the application's environment map.
+     * @param name - The name of the environment variable.
+     * @param def_value - An optional default value to return if the variable is not found.
+     * @returns The value of the environment variable, or `def_value` if not found.
+     */
+
 	static fireGlobal( msg: string, params?: any ) {
 		Application.instance().fire( "global", { msg, params } );
 	}
@@ -123,20 +195,29 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
 		} );
 	}
 
+	/**
+     * Moves focus to the next or previous focusable element within the application.
+     * Handles Tab and Shift+Tab key presses.
+     * @param next - If `true`, focus moves to the next element; if `false`, to the previous.
+     * @returns `true` if focus was successfully moved, `false` otherwise.
+     */
+
 	focusNext( next: boolean ) {
 		let act = document.activeElement;
 		let topmost: HTMLElement;
 
 		while( act!=document.body ) {
 			const comp = componentFromDOM(act);
-			const ifx = comp.queryInterface( "tab-handler") as ITabHandler;
+			if( comp ) {
+				const ifx = comp.queryInterface( "tab-handler") as ITabHandler;
 
-			if( ifx ) {
-				return ifx.focusNext( next );
-			}
+				if( ifx ) {
+					return ifx.focusNext( next );
+				}
 
-			if( act.classList.contains("x4box") ) {	// todo: that is too dirty
-				topmost = act as HTMLElement;
+				if( act.classList.contains("x4box") ) {	// todo: that is too dirty
+					topmost = act as HTMLElement;
+				}
 			}
 
 			act = act.parentElement;
@@ -169,10 +250,13 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
 		return false;
 	}
 
-
 	/**
-	 * 
-	 */
+     * Sets up WebSocket messaging for the application.
+     * All 'global' messages fired via the application will be sent over the WebSocket,
+     * and messages received from the WebSocket will be re-fired as 'global' messages.
+     * @param path - Optional WebSocket path. If not provided, it defaults to `ws://hostname:port/ws`.
+     * @param looseCallback - A callback function to be executed when the WebSocket connection is closed unexpectedly.
+     */
 
 	setupSocketMessaging( path?: string, looseCallback?: ( ) => void ) {
 		
@@ -231,15 +315,21 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
 	}
 
 	/**
-	 * get a local storage value
-	 * @param name name of the value
-	 * @returns the value (string) or undefined
-	 */
+     * Retrieves a value from the browser's local storage.
+     * @param name - The key of the value to retrieve.
+     * @returns The stored value as a string, or `null` if not found.
+     */
 
 	getStorage( name: string ) : string {
 		return localStorage.getItem( name );
 	}
 
+	/**
+     * Retrieves and parses a JSON value from the browser's local storage.
+     * @param name - The key of the JSON value to retrieve.
+     * @returns The parsed JSON object, or `undefined` if not found or parsing fails.
+     */
+
 	getStorageJSON( name: string ) : any {
 		try {
 			return JSON.parse( localStorage.getItem( name ) );
@@ -250,15 +340,22 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
 	}
 
 	/**
-	 * change a loclastorage value
-	 * @param name name of the value
-	 * @param value the value to store
-	 */
+     * Stores a string or number value in the browser's local storage.
+     * The value will be converted to a string before storage.
+     * @param name - The key under which to store the value.
+     * @param value - The value to store.
+     */
 
 	setStorage( name: string, value: string | number ) {
 		localStorage.setItem( name, value+'' );
 	}
 
+	/**
+     * Stores an object as a JSON string in the browser's local storage.
+     * @param name - The key under which to store the JSON value.
+     * @param value - The object to serialize and store.
+     */
+	
 	setStorageJSON( name: string, value: any ) {
 		localStorage.setItem( name, JSON.stringify( value ) );
 	}