x4js 2.2.32 → 2.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.2.32",
+  "version": "2.2.33",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",
@@ -36,7 +36,6 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "tsx": "^4.22.4",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.12.0"
   }

package/src/components/monaco/monaco.ts

@@ -1,11 +1,12 @@
-import { class_ns, Component, ComponentProps } from '../../x4.js';
+import { class_ns } from '../../core/core_tools';
+import { Component, ComponentProps } from '../../core/component';
 
 import Monaco from './bin/monaco'; 
 import "./monaco.module.scss"
 
 
 interface MonacoEditorProps extends ComponentProps {
-	language: "typescript" | "javascript" | "json" | "css" | "html";
+	language: "typescript" | "javascript" | "json" | "css" | "html" | string;
 	theme?: string;
 	content?: string;
 	options?: Monaco.editor.IEditorOptions & Monaco.editor.IGlobalEditorOptions;
@@ -14,24 +15,22 @@ interface MonacoEditorProps extends ComponentProps {
 @class_ns( "x4" )
 export class MonacoEditor extends Component<MonacoEditorProps> {
 
-	static initCount = 0;
-	static basePath: string = "monaco/";
-	static monaco: typeof Monaco;
-	static initCbs: Function[] = [];
+	private static _initCount = 0;
+	private static _basePath: string = "monaco/";
+	private static _monaco: typeof Monaco;
+	private static _initCbs: Function[] = [];
 
 	private _editor: Monaco.editor.IStandaloneCodeEditor;
 
-	static async start( ) { 
-		if( this.initCount ) {
+	static async _start( ) { 
+		if( this._initCount ) {
 			return;
 		}
 
-        // path must be hard coded for esbuild to work
+        // dynamic import (without esbuild intervention)
         const dynamicImport = new Function("path", "return import('./'+path)");
-        this.monaco = (await dynamicImport(this.basePath + "monaco.js")).default;
-        //this.monaco = (await import(`${this.basePath}monaco.js`)).default;
-		//this.monaco = (await import( "./bin/monaco.js" )).default;
-		this.initCount++;
+        this._monaco = (await dynamicImport(this._basePath + "monaco.js")).default;
+		this._initCount++;
 
 		globalThis.MonacoEnvironment = {
 			getWorkerUrl: function (_moduleId, label) {
@@ -53,8 +52,8 @@ export class MonacoEditor extends Component<MonacoEditorProps> {
 					workerPath = "editor.worker.js";
 				}
 
-				const fullpath = MonacoEditor.basePath+'workers/'+workerPath;
-				console.log( `getting "${label} path: ${fullpath}` );
+				const fullpath = MonacoEditor._basePath+'workers/'+workerPath;
+				//console.log( `getting "${label} path: ${fullpath}` );
 				return fullpath;
 			}
 		};
@@ -62,7 +61,7 @@ export class MonacoEditor extends Component<MonacoEditorProps> {
         // custom append css
 		const link = document.createElement('link');
         link.rel = 'stylesheet';
-        link.href = MonacoEditor.basePath+'monaco.css';
+        link.href = MonacoEditor._basePath+'monaco.css';
         link.type = 'text/css';
         document.head.appendChild(link);
 	}
@@ -70,16 +69,16 @@ export class MonacoEditor extends Component<MonacoEditorProps> {
 	static addTypelib( name: string, code: string ) {
 		const register = ( ) => {
 			///@ts-ignore
-			const ts = MonacoEditor.monaco.languages.typescript;
+			const ts = MonacoEditor._monaco.languages.typescript;
 			///@ts-ignore
 			ts.typescriptDefaults.addExtraLib( code, `ts:filename/${name}`);
 		}
 
-		if( MonacoEditor.monaco ) {
+		if( MonacoEditor._monaco ) {
 			register( );
 		}
 		else {
-			this.initCbs.push( register );
+			this._initCbs.push( register );
 		}
 	}
 
@@ -89,11 +88,11 @@ export class MonacoEditor extends Component<MonacoEditorProps> {
 
 		super( props );
 
-		MonacoEditor.start( )
+		MonacoEditor._start( )
 			.then( ( ) => {
-				MonacoEditor.initCbs.forEach( x => x() );
+				MonacoEditor._initCbs.forEach( x => x() );
 
-				this._editor = MonacoEditor.monaco.editor.create( this.dom as HTMLElement, {
+				this._editor = MonacoEditor._monaco.editor.create( this.dom as HTMLElement, {
 					value: content,
 					language: props.language,
 					theme: props.theme,
@@ -112,5 +111,25 @@ export class MonacoEditor extends Component<MonacoEditorProps> {
 			}
 		})
 	}
+
+	setTheme( name: string ) {
+		MonacoEditor._monaco.editor.setTheme( name );
+	}
+
+	queryInterface<T>(name: string): T {
+		if( name=='tab-handler' ) {
+			const rc = {
+				focusNext: ( ) : boolean => { return false; }
+			}
+			return rc as T;
+		}
+
+		return super.queryInterface( name );
+	}
+
+	static async monaco( ) {
+		await this._start( );
+		return this._monaco;
+	}
 }
 

package/src/core/component.ts

@@ -20,6 +20,7 @@ import { AriaAttributes, unitless } from './core_styles';
 import { CoreEvent, EventMap } from './core_events';
 import { addEvent, DOMEventHandler, GlobalDOMEvents } from './core_dom';
 import { Application, EvMessage } from './core_application';
+import { makeState } from './core_state.js';
 
 interface RefType<T extends Component> {
 	dom: T;
@@ -164,7 +165,7 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 	protected readonly clsprefix: string;	// internal class name prefix (x4 internal)
 
 	#store: Map<string|symbol,any>;
-
+	#pstate: any;
 	
 	constructor( props: P ) {
 		super( );
@@ -1156,6 +1157,41 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 	queryInterface<T>( name: string ): T {
 		return null;
 	}
+
+	// :: PERSISTENCE ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+	protected loadPState( name: string, defaults: Record<string, any> ): any {
+
+		if( !this.#pstate ) {
+			this.#pstate = {};
+		}
+
+		if( this.#pstate[name] ) {
+			return this.#pstate[name];
+		}
+
+		const key = `x4@persist:${name}`;
+
+		let raw: Record<string, any>;
+		try {
+			const stored = Application.instance().getStorage( key );
+			raw = stored ? { ...defaults, ...JSON.parse( stored ) } : { ...defaults };
+		}
+		catch {
+			raw = { ...defaults };
+		}
+
+		const state = makeState( raw );
+
+		state.on( "change", ( ) => {
+			this.setTimeout( key, 500, ( ) => {
+				Application.instance().setStorage( key, JSON.stringify( raw ) );
+			});
+		});
+
+		this.#pstate[name] = state;
+		return state;
+	}
 }  
 
 

package/src/core/core_application.ts

@@ -155,7 +155,7 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
      * @param value - The value to store for the environment variable.
      */
 
-	setEnv( name: string, value: any ) {
+	setEnv<T = any>( name: string, value: T ) {
 		this.env.set( name, value );
 	}
 
@@ -166,7 +166,7 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
      * @returns The value of the environment variable, or `def_value` if not found.
      */
 	
-	getEnv( name: string, def_value?: any ) {
+	getEnv<T = any>( name: string, def_value?: T ) : T {
 		return this.env.get( name ) ?? def_value;
 	}
 

package/src/core/core_state.ts

@@ -4,64 +4,227 @@
 * @copyright (c) 2025 R-libre ingenierie, all rights reserved.
 **/
 
+import { CoreEvent, EventMap, EventSource } from './core_events.js';
+import { isPlainObject } from './core_tools.js';
+
+type StateData = boolean | number | string | Date | unknown;
+type State = Record<string, StateData>;
+
+export interface EvStateChange extends CoreEvent {
+	readonly path: string;
+	readonly value: any;
+}
+
+export interface StateEvents extends EventMap {
+	change: EvStateChange;
+}
+
+/**
+ * type of the proxified state: the data itself + the manager's event API.
+ * Pick<> avoids re-declaring the signatures — if on/off/once evolve
+ * in StateManager, this type follows automatically.
+ */
+
+export type StateProxy<T extends State> = T & Pick<StateManager<T>, "on" | "off" | "once" | "watch">;
 
-type StateData = boolean | number | string | Date | any;
-type State = Record<string,StateData>;
 
 /**
- * @experimental
+ * true for values that must be wrapped in a proxy when accessed
+ * (plain objects & arrays — excludes null, Date, RegExp, Map, Set,
+ * class instances, ...)
  */
 
-export class StateManager {
-	
-	private _state: StateData;
-	private _subscribers: Map<string,any>;
-	private _currentTracking: Set<string>;
+function _is_proxyable( value: any ): boolean {
+	return value !== null && typeof value === "object" && ( Array.isArray( value ) || isPlainObject( value ) );
+}
 
-	constructor(initialState: StateData ) {
-		this._state = initialState ? { ...initialState } : {};
-		this._subscribers = new Map();
-		this._currentTracking = new Set( );
+/**
+ * append a segment to a dotted path, using bracket notation
+ * for array indices: "items[3].name" instead of "items.3.name"
+ */
+function _child_path( path: string, prop: string, target: any ): string {
+	if( Array.isArray( target ) && /^\d+$/.test( prop ) ) {
+		return `${path}[${prop}]`;
 	}
+	return path ? `${path}.${prop}` : prop;
+}
 
-	getState( path: string, defaultValue: StateData = null) {
-		// Optional tracking for reactivity
-		if (this._currentTracking) {
-			this._currentTracking.add(path);
-		}
-		
-		// Fast path-based access
-		const parts = path.split('.');
-		let current = this._state;
-
-		for (const part of parts) {
-			if (current?.[part] === undefined) {
-				return defaultValue;
-			}
+/**
+ * true when 'path' is 'watched' itself or one of its descendants:
+ *   _path_matches( "user",      "user" )        → true  (the value itself)
+ *   _path_matches( "user.name", "user" )        → true  (descendant)
+ *   _path_matches( "user.tags[2]", "user.tags") → true  (array element)
+ *   _path_matches( "username",  "user" )        → false (boundary check)
+ */
+function _path_matches( path: string, watched: string ): boolean {
+	if( !path.startsWith(watched) ) return false;
+	if( path.length===watched.length ) return true;
+
+	const c = path[watched.length];
+	return c==='.' || c==='[';
+}
 
-			current = current[part];
+/**
+ * 
+ */
+
+export class StateManager<T extends State> extends EventSource<StateEvents> {
+
+	private _state: T;
+	private _proxy: StateProxy<T> | undefined;
+
+	/**
+	 * raw object → proxy cache, scoped to THIS manager
+	 * - avoids re-creating a proxy on every get
+	 * - guarantees referential identity: state.user === state.user
+	 * - WeakMap: entries are collected with their objects, and the whole cache is collected with the manager
+	 * - instance-scoped (not module-level) so the same raw object referenced by two different managers never gets a proxy bound to the wrong manager/path
+	 */
+
+	private _cache = new WeakMap<object, any>( );
+
+	constructor( initialState: T ) {
+		super( );
+		this._state = { ...initialState };
+	}
+
+	proxify( ): StateProxy<T> {
+
+		if( !this._proxy ) {
+			// event API attached as non-enumerable properties on the raw root object: invisible to for...in / Object.keys 
+			// OR JSON.stringify, and served by the get trap with no special handling
+
+			Object.defineProperties( this._state, {
+				on:   { value: this.on.bind( this ),   enumerable: false },
+				off:  { value: this.off.bind( this ),  enumerable: false },
+				once: { value: this.once.bind( this ), enumerable: false },
+				watch: { value: this.watch.bind( this ), enumerable: false },
+			});
+
+			this._proxy = this._mk_proxy( this._state, "" );
 		}
 
-		return current;
+		return this._proxy;
 	}
 
-	setState(path: string, value: StateData, context: any = {} ) {
-		// Update state
-		const parts = path.split('.');
-		let current = this._state;
+	/**
+	 * create a lazy proxy: sub-objects and arrays are only wrapped
+	 * when actually accessed, and are never copied — the original
+	 * object remains the single source of truth.
+	 */
+
+	private _mk_proxy( obj: any, path: string ): any {
+
+		const cached = this._cache.get( obj );
+		if( cached ) return cached;
+
+		const proxy = new Proxy( obj, {
 
-		for (let i = 0; i < parts.length - 1; i++) {
-			const part = parts[i];
-			if (!current[part] || typeof current[part] !== 'object') {
-				current[part] = {};
+			get: ( target, prop, receiver ) => {
+
+				// symbols (Symbol.iterator, Symbol.toPrimitive, devtools inspection...): 
+				// pass-through, never an error nor a wrap
+				if( typeof prop === "symbol" ) {
+					return Reflect.get( target, prop, receiver );
+				}
+
+				// genuinely missing property ('in' walks the prototype chain, so array methods, toString, toJSON... never trigger a false positive)
+				if( !( prop in target ) ) {
+					console.error( `state error, unable to find ${_child_path(path,prop,target)}` );
+					return undefined;
+				}
+
+				const value = Reflect.get( target, prop, receiver );
+
+				// wrap on demand, only what is actually read
+				if( _is_proxyable( value ) ) {
+					return this._mk_proxy( value, _child_path( path, prop, target ) );
+				}
+
+				return value;
+			},
+
+			set: ( target, prop, value, receiver ) => {
+
+				// no notification when the value doesn't change
+				// (avoids noise and listener → set → listener loops)
+				if( Reflect.get( target, prop, receiver ) === value ) {
+					return true;
+				}
+
+				Reflect.set( target, prop, value, receiver );
+
+				// no readable path for a symbol: assign without firing
+				if( typeof prop === "string" ) {
+					this.fire( "change", { path: _child_path(path,prop,target), value } );
+				}
+
+				return true;
+			},
+
+			deleteProperty: ( target, prop ) => {
+
+				if( !( prop in target ) ) return true;
+
+				delete target[prop];
+
+				if( typeof prop === "string" ) {
+					this.fire( "change", { path: _child_path(path,prop,target), value: undefined } );
+				}
+
+				return true;
 			}
-			
-			current = current[part];
+		});
+
+		this._cache.set( obj, proxy );
+		return proxy;
+	}
+
+	on<K extends keyof StateEvents>( name: K, listener: ( ev: StateEvents[K] ) => void ) {
+		this.addListener( name, listener );
+		return {
+			off: ( ) => this.removeListener( name, listener )
 		}
+	}
 
-		current[parts[parts.length - 1]] = value;
+	off<K extends keyof StateEvents>( name: K, listener: ( ev: StateEvents[K] ) => void ) {
+		this.removeListener( name, listener );
+	}
+
+	once<K extends keyof StateEvents>( name: K, listener: ( ev: StateEvents[K] ) => void ) {
+		const handle = this.on( name, ( e ) => {
+			handle.off( );
+			listener( e );
+		});
+		return handle;
+	}
 
-		// Notify subscribers
-		//this._notifySubscribers(path, value);
+	/**
+	 * observe changes on a specific path and everything below it.
+	 * fires for the path itself and for any descendant:
+	 *   watch( "user", cb )  →  fires on user, user.name, user.tags[0], ...
+	 * returns a handle with off() to unsubscribe.
+	 */
+	watch( path: string, cb: ( ev: EvStateChange ) => void ) {
+		return this.on( "change", e => {
+			if( _path_matches( e.path, path ) ) {
+				cb( e );
+			}
+		});
 	}
-}
+}
+
+
+/**
+ * create a ready-to-use reactive state
+ *
+ * const state = makeState( { count: 0, items: [1,2,3] } );
+ * state.on( "change", e => console.log( e.path, "=", e.value ) );
+ * state.count++;         // "count = 1"
+ * state.items.push( 4 ); // "items.3 = 4"
+ */
+
+export function makeState<T extends State>( initialState: T ): StateProxy<T> {
+	return new StateManager( initialState ).proxify( );
+}
+

package/src/core/core_tools.ts

@@ -328,9 +328,12 @@ export class Timer {
 			this.clearTimeout(name);
 		}
 
-		const tm = setTimeout(callback, time);
-		this._timers.set(name, tm);
+		const tm = setTimeout( ( ) => {
+			this._timers?.delete( name );
+			callback( );
+		}, time);
 
+		this._timers.set(name, tm);
 		return tm;
 	}
 
@@ -373,6 +376,10 @@ export class Timer {
 
 		this._timers = null;
 	}
+
+	debounce( name: string, time: number, callback: Function ) {
+		this.setTimeout( name, time, callback );
+	}
 }
 
 /**
@@ -1018,4 +1025,98 @@ export function sanitizeHtml( input: string ): string {
 export function safeText( v: string | UnsafeHtml ): string {
 	if( !v ) { return ""; }
     return v instanceof UnsafeHtml ? v.toString() : sanitizeHtml( v );
-}
+}
+
+
+/**
+ * split a dotted path into segments.
+ *   "user.name"      → [ "user", "name" ]
+ *   "user.tags[2]"   → [ "user", "tags", "2" ]
+ *   "items[0][1]"    → [ "items", "0", "1" ]
+ */
+function _parse_path( path: string ): string[] {
+
+	const segments: string[] = [];
+
+	for( const part of path.split( '.' ) ) {
+		// "tags[2]" → "tags" then "2" ; "name" → "name"
+		let rest = part;
+
+		const bracket = rest.indexOf( '[' );
+		if( bracket < 0 ) {
+			segments.push( rest );
+			continue;
+		}
+
+		if( bracket > 0 ) {
+			segments.push( rest.substring( 0, bracket ) );
+		}
+
+		// consume every [n] group
+		const re = /\[(\d+)\]/g;
+		let m;
+		while( ( m = re.exec( rest ) ) !== null ) {
+			segments.push( m[1] );
+		}
+	}
+
+	return segments;
+}
+
+
+/**
+ * walk down 'obj' following 'segments', stopping before the last one.
+ * returns the parent object of the final segment, or undefined if
+ * the path is broken somewhere.
+ */
+function _walk_to_parent( obj: any, segments: string[] ): any {
+
+	let current = obj;
+
+	for( let i = 0; i < segments.length - 1; i++ ) {
+		if( current === null || current === undefined ) {
+			return undefined;
+		}
+		current = current[segments[i]];
+	}
+
+	return current;
+}
+
+
+/**
+ * read the value at the given path.
+ *   getMemberValue( state, "user.tags[2]" )
+ */
+
+export function getMemberValue( obj: any, path: string ): any {
+
+	const segments = _parse_path( path );
+	const parent = _walk_to_parent( obj, segments );
+
+	if( parent === undefined || parent === null ) {
+		return undefined;
+	}
+
+	return parent[ segments[segments.length - 1] ];
+}
+
+
+/**
+ * write the value at the given path.
+ * silently does nothing if an intermediate segment is missing
+ */
+
+export function setMemberValue( obj: any, path: string, value: any ) : boolean {
+
+	const segments = _parse_path( path );
+	const parent = _walk_to_parent( obj, segments );
+
+	if( parent === undefined || parent === null ) {
+		return false;
+	}
+
+	parent[ segments[segments.length - 1] ] = value;
+	return true;
+}
+