x4js 2.2.32 → 2.2.34

package/README.md

@@ -1,14 +1,5 @@
-
-# x4 framework
-
-This is the x4 framework repository.
-
-X4 is a full typescript framework to develop Web or Desktop applications.
-Included more than 50 controls like grids, charts, etc. 
-
-Everything needed to push the limits of your creativity.
-
-If these components are not enough, you can create your in few lines.
+# x4js
+**A TypeScript framework for people who build applications, not markup.**
 
 ## Home page
 see [home](https://x4js.org)
@@ -17,11 +8,100 @@ see [home](https://x4js.org)
 see [API](https://rlibre.github.io/x4/index.html)
 see [AI](./aicontext.md)
 
+---
+
+## The translation you never signed up for
+
+Modern web frameworks share a hidden assumption: that your job is to describe the DOM. Whether through JSX, templates, or reactive object trees, they all keep you close to the metal — writing `<div>`s, wiring class names, juggling attributes. You spend your days translating what you *mean* into how the browser *renders it*, then debugging the translation.
+
+x4js removes that layer entirely.
+
+You don't assemble elements. You compose high-level objects — `Button`, `DataGrid`, `Dialog`, `Form` — that model your application, not the page. A button has a `text`, not a `textContent`. A grid has columns, not a `<table><thead><tr>`. You describe intent; the framework handles the rest.
+
+---
+
+## The paradox nobody talks about
+
+Millions of developers building with reactive frameworks — React, Vue, Svelte, and the rest — spend their day inside VS Code, Slack, Figma, Discord. Applications they hold up as benchmarks of speed and polish.
+
+Not one of them is built the way those same developers build their own work.
+
+VS Code is written in TypeScript, around high-level object components, with direct, surgical DOM manipulation — **no virtual DOM**. That isn't an accident. Routing every keystroke through a virtual-tree reconciliation pass would make a code editor unusable. So the tool you use to write your reactive app could never have been written in that same reactive framework and stayed fast.
+
+This isn't an isolated curiosity. It's a pattern. The applications that must be genuinely fast — editors, IDEs, terminals, design tools, spreadsheets — converge on the same architecture again and again: object components, direct DOM updates, fine-grained and intentional reactivity. Exactly the philosophy x4js is built on.
+
+The virtual DOM is a comfortable abstraction that trades performance for ease of reasoning. It's a fair trade for a landing page, a dashboard, a form. But the moment an interface becomes dense, dynamic, and latency-sensitive, the teams building the industry's reference tools quietly abandon that trade. They don't choose it for their own product — they only recommend it for everyone else's.
+
+> When performance actually matters, the industry votes with its code.
+> x4js brings to *your* applications the architecture your tools already use for theirs.
+
+A fair caveat: VS Code doesn't run on x4js, and reactive frameworks aren't "bad." React, Vue, and Svelte optimize for a different problem — productivity on interfaces of moderate complexity — and they do it well. The point is architectural family, not brand. x4js belongs to the same lineage as the dense, demanding tools you already trust: object-first, direct-DOM, precisely reactive.
+
+---
+
+## Why the object-first approach wins
+
+### No virtual DOM, no diffing
+
+x4js builds and updates the real DOM directly. There's no reconciliation pass, no shadow tree to compare against, no per-render overhead. Updates are direct — which makes them fast and, just as importantly, predictable.
+
+### Code that runs when you call it — and only then
+
+In a reactive framework, your component is a function the framework re-executes whenever it decides to. Every variable is recreated on each pass; every closure can silently capture a stale value. Entire categories of bugs — stale closures, dependency arrays, effects firing twice, memoization tuning — exist *only* because the execution model is inverted: the framework calls you.
+
+An x4js component is an object. Its state lives in fields that persist for its whole lifetime. Its methods run when you call them, once, in the order you wrote. There is nothing to memoize, no dependency list to maintain, no rule about where you're allowed to declare things. The mental model is the one you already have from every other kind of software you've written.
+
+### State you can simply assign
+
+In reactive frameworks, changing a value is a discipline in itself. State is immutable, so a one-field update becomes a pyramid of spreads: `setUser({ ...user, address: { ...user.address, city: "Paris" } })` — and entire libraries exist just to make that bearable. State setters are asynchronous and batched, so the line after `setCount(count + 1)` still reads the old value; you must remember updater functions (`setCount(c => c + 1)`) or debug why your counter skips. And the primitives themselves come with a rulebook — hooks only at the top level, never in a condition or a loop, always in the same order — rules the language cannot enforce, so a linter has to police your code where the compiler should have.
+
+None of this is your application. All of it is ceremony imposed by the framework's model of change.
+
+In x4js, state is an object and change is assignment: `state.count++`, `state.user.address.city = "Paris"`. The value is updated on the next line, because of course it is. Deep mutation works, because objects are objects. There are no placement rules, because a property assignment is not a framework primitive — it's JavaScript. Years of accumulated workarounds — updater callbacks, spread pyramids, immutability helpers, exhaustive-deps lint rules — simply have nothing left to fix.
+
+### Debugging your code, not the framework's
+
+Set a breakpoint in an x4js method and the call stack reads like your application: your event handler, your component, your logic. In virtual-DOM frameworks, the same breakpoint lands you in a scheduler — fiber trees, hook lists, reconciliation frames — with your actual code buried somewhere inside the machinery. Dedicated browser devtools extensions exist for those frameworks precisely because the native debugger stopped being enough. x4js needs none: what you wrote is what executes, and the standard debugger tells the whole story.
+
+### No re-render tax on memory
+
+A virtual-DOM render allocates a full tree of description objects — on every update, for every component involved — and immediately hands it to the garbage collector once diffed. Under load (typing, scrolling, dragging), that is a constant allocation churn competing with your application for CPU and memory. x4js components are allocated once and mutated in place. A text change is a property assignment and one DOM write. Nothing to allocate, nothing to collect, nothing to diff.
+
+### Built for dense, professional interfaces
+
+Reactive ecosystems treat data grids, tree views, dockable panels, and virtual scrolling as third-party problems — an `npm install` and a licensing page away. That is because rendering ten thousand live rows through a diffing pipeline is genuinely hard, so the hard components get outsourced. In x4js, the demanding components are first-class citizens of the framework itself, built on the same direct-DOM foundation as everything else. Business applications — the ones with toolbars, grids, trees, and forms that people use eight hours a day — are the primary use case, not an afterthought.
+
+### No build step required
+
+No JSX to transpile, no template compiler, no toolchain to configure. x4js is TypeScript that runs. You get type safety and autocompletion out of the box, with nothing standing between your source and your running app — and nothing in your supply chain but the compiler you already trust.
+
+### An API that survives the churn
+
+The reactive world reinvents itself every few years: class components gave way to hooks, options API to composition API, stores to signals — each transition deprecating the patterns, tutorials, and muscle memory of the previous one. Code written against browser primitives and plain TypeScript objects doesn't churn like that. `Proxy`, `EventTarget`, classes, and the DOM are stable, standardized ground. An x4js codebase written today will compile and run unchanged years from now, because there is no framework-specific paradigm to be deprecated out from under it.
+
+### You ship what you use — nothing else
+
+Reactive frameworks make you ship their runtime before your first component renders: the scheduler, the reconciler, the hooks machinery — a fixed entry fee, paid by every user on every load, whether your page is an app or a button. x4js has no such core tax. Components are plain TypeScript classes, so standard tree-shaking keeps exactly what you import: use only `Button`, and your bundle contains `Button` — about 22 KB, core included. No runtime to amortize, no framework floor below which your app cannot shrink. Small tools stay small; big applications pay only for the components they actually use.
+
+If you come from C or C++, you already know this model: it's **static linking against a library**. The linker pulls in only the symbols you reference, dead code never makes it into the binary. A reactive framework's runtime is the opposite — a mandatory DLL shipped whole with every executable, whether you call one function from it or a thousand. x4js links; it doesn't bundle a runtime.
+
+### End-to-end TypeScript
+
+Components, properties, and events are fully typed. The compiler catches mistakes before the browser does — not only in your logic, but in the way your components fit together.
+
+### One codebase, web and desktop
+
+Because x4js produces standard DOM from plain TypeScript — no framework-specific runtime, no build-time magic — the same application runs unchanged in the browser or packaged as a desktop app through Electron, Tauri, or NW.js. Nothing to adapt, nothing to port: the wrapper provides the window, x4js provides the application.
+
+---
+
+**Think differently. Escape the DOM. Focus on the concept, not the format.**
+
 ## Ideas
 
 [x] aicontext.md
-[ ] finish StateManager
-[ ] review core_data
+[x] finish StateManager
+[x] review core_data
 [ ] doc doc and doc
 [ ] demo with all best practices
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.2.32",
+  "version": "2.2.34",
   "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

@@ -16,6 +16,30 @@
 
 import { _tr } from "./core_i18n.js";
 
+
+// todo: split into 2 files
+//	core_tools & core_dom_tools
+
+//		isFeatureAvailable → "EyeDropper" in window
+//		asap → requestAnimationFrame (n'existe pas en Node ; Deno l'a)
+//		beep → new Audio(...) + .play()
+//		getScrollbarSize → document.createElement, document.body
+//		getGlobalZoom → window.getComputedStyle, document.body
+//		getSystemMetrics → appelle les deux précédentes
+//		setWaitCursor → document.body.style
+//		getFocusableElements → root.querySelectorAll, HTMLElement
+//		Element en paramètre de type (DOM lib)
+
+
+
+
+
+
+
+
+
+
+
 /**
  * @returns true if object is a string
  */
@@ -328,9 +352,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 +400,10 @@ export class Timer {
 
 		this._timers = null;
 	}
+
+	debounce( name: string, time: number, callback: Function ) {
+		this.setTimeout( name, time, callback );
+	}
 }
 
 /**
@@ -1018,4 +1049,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;
+}
+