x4js 2.0.28 → 2.0.30

package/src/core/core_data.ts

@@ -17,7 +17,7 @@
 
 import { EvChange } from './component';
 import { CoreElement } from './core_element';
-import { CoreEvent, EventCallback, EventMap, EventSource } from './core_events';
+import { CoreEvent, EventMap, EventSource } from './core_events';
 import { isArray, isString } from './core_tools';
 
 export type DataRecordID = any;
@@ -80,24 +80,26 @@ function _getMetas( obj: object, create = true ) : MetaInfos {
 	let mfld = Object.prototype.hasOwnProperty.call(ctor,metaFields) ? ctor[metaFields] : undefined;
 	
 	if( mfld===undefined ) {
-		if( !create ) {
+		if( !create && ctor!=DataModel ) {
 			console.assert( mfld!==undefined );
 		}
 		
 		// construct our metas
 		mfld = new MetaInfos( ctor.name );
 
-		// merge with parent class metas
-		let pctor = Object.getPrototypeOf(ctor);
-		if( pctor!=DataModel ) {
-			let pmetas = pctor[metaFields];
-			mfld.fields = [...pmetas.fields, ...mfld.fields ]
-			
-			console.assert( mfld.id===undefined, 'cannot define mutiple record id' );
-			if( !mfld.id ) {
-				mfld.id = pmetas.id;
-			}
-		}	
+        if( ctor!=DataModel ) { //<eco: allow addFields on DataModel
+            // merge with parent class metas
+            let pctor = Object.getPrototypeOf(ctor);
+            if( pctor!=DataModel ) {
+                let pmetas = pctor[metaFields];
+                mfld.fields = [...pmetas.fields, ...mfld.fields ]
+                
+                console.assert( mfld.id===undefined, 'cannot define mutiple record id' );
+                if( !mfld.id ) {
+                    mfld.id = pmetas.id;
+                }
+            }	
+        }
 
 		(obj.constructor as any)[metaFields] = mfld;
 	}
@@ -249,7 +251,24 @@ export namespace data {
  * record model
  */
 
-export class DataModel {
+export class DataModel<T = any> {
+
+    /**
+     * dynamic DataModel
+     */
+
+    addField( ...fields: FieldInfo[] ) {
+        if( fields.length==0 ) {
+            return;
+        }
+
+        let metas = _getMetas( this, false );
+        if( metas.fields.length==0 ) {
+            metas.id = fields[0].name;
+        }
+
+        metas.fields.push( ...fields );
+    }
 
 	/**
 	 * MUST IMPLEMENT
@@ -309,8 +328,6 @@ export class DataModel {
 
 		return rec as T;
 	}
-
-
 	
 	/**
 	 * default unserializer
@@ -318,10 +335,10 @@ export class DataModel {
 	 * @returns a new Record
 	 */
 
-	unSerialize(data: any, id?: DataRecordID ) : DataRecord { 
+	unSerialize(data: any, id?: DataRecordID ) : DataRecord<T> { 
 
 		const fields = this.getFields();
-		const rec = new DataRecord( );
+		const rec: any = {};
 
 		fields.forEach( (sf) => {
 			let value = data[sf.name];
@@ -457,63 +474,9 @@ export class DataModel {
  * 
  */
 
-export class DataRecord {
-	[ key: string ]: DataFieldValue;
-
-	/*
-	/ **
-	 * @returns fields descriptors
-	 * /
-
-	getFields(): FieldInfo[] { 
-		let metas = _getMetas( this, false );
-		return metas.fields;
-	}
-
-	
-
-	/ **
-	 * 
-	 * @param name 
-	 * @param data 
-	 * /
-
-	setRaw( name: string, data: string ) {
-		this[name] = data;
-	}
-
-	
-
-	/ **
-	 * set field value
-	 * @param name - field name
-	 * @param value - value to set
-	 * @example
-	 * record.set( 'field1', 7 );
-	 * /
-
-	setField(name: string, value: any) {
-		let fields = this.getFields( );
-		let idx = fields.findIndex( fi => fi.name == name );
-
-		if( idx < 0 ) {
-			console.assert( false, 'unknown field: '+name);
-			return;
-		}
-
-		let fld = fields[idx];
-		if( fld.calc!==undefined ) {
-			console.assert( false, 'cannot set calc field: '+name);
-			return;
-		}
-		
-		this.setRaw( fld.name, value );
-	}
-	*/
-
-	
-}
-
+export type DataRecord<T = any> = Partial<T> & {
+    [key: string]: any;
+};
 
 /**
  * 
@@ -591,11 +554,11 @@ interface DataStoreEventMap extends EventMap {
  * 
  */
 
-export class DataStore extends EventSource<DataStoreEventMap> {
+export class DataStore<T = any> extends EventSource<DataStoreEventMap> {
 	
-	protected m_model: DataModel;
+	protected m_model: DataModel<T>;
 	protected m_fields: FieldInfo[];
-	protected m_records: DataRecord[];
+	protected m_records: DataRecord<T>[];
 
 	protected m_proxy: DataProxy;
 	protected m_rec_index: DataIndex;
@@ -648,7 +611,7 @@ export class DataStore extends EventSource<DataStoreEventMap> {
 
 	public setData( records: any[] ) {
 
-		const realRecords: DataRecord[] = new Array( records.length );
+		const realRecords: DataRecord<T>[] = new Array( records.length );
 
 		records.forEach( (rec,idx) => {
 			realRecords[idx] = this.m_model.unSerialize(rec);
@@ -697,11 +660,11 @@ export class DataStore extends EventSource<DataStoreEventMap> {
 	 * @param data 
 	 */
 
-	public append( rec: DataRecord | any ) {
+	public appendRaw( rec: T ) {
+		return this.append( this.m_model.unSerialize( rec ) );
+	}
 
-		if( !(rec instanceof DataRecord) ) {
-			rec = this.m_model.unSerialize( rec );
-		}
+	public append( rec: DataRecord ) {
 
 		const id = this.m_model.getID(rec);
 		console.assert( id!==undefined );
@@ -797,12 +760,13 @@ export class DataStore extends EventSource<DataStoreEventMap> {
 		return -1;
 	}
 
+
 	/**
 	 * return the record by it's id 
 	 * @returns record or null
 	 */
 
-	public getById(id: DataRecordID): DataRecord {
+	public getById(id: DataRecordID): DataRecord<T> {
 		let idx = this.indexOfId( id );
 		if( idx<0 ) {
 			return null;
@@ -817,12 +781,12 @@ export class DataStore extends EventSource<DataStoreEventMap> {
 	 * @returns record or null
 	 */
 
-	public getByIndex( index: number ): DataRecord {
+	public getByIndex( index: number ): DataRecord<T> {
 		let idx = this.m_rec_index[index];
 		return this._getRecord( idx );
 	}
 
-	private _getRecord( index: number ) : DataRecord {
+	private _getRecord( index: number ) : DataRecord<T> {
 		return this.m_records[index] ?? null;
 	}
 
@@ -1065,6 +1029,29 @@ export class DataStore extends EventSource<DataStoreEventMap> {
 		}
 	}
 
+	find( cb: ( rec: DataRecord ) => boolean ) {
+		let result;
+
+		if( this.m_rec_index ) {
+			result = this.m_rec_index.find( ri => {
+				if( cb( this.m_records[ri] ) ) {
+					return true;
+				}
+			});
+		}
+		else {
+			result = this.m_records.findIndex( rec => {
+				if( rec ) {
+					if( cb( rec ) ) {
+						return true;
+					}
+				}
+			} );
+		}
+
+		return result>=0 ? this.getByIndex(result) : null;
+	}
+
 	export( ) {
 		return this.m_records;
 	}

package/src/core/core_dom.ts

@@ -93,7 +93,10 @@ function observeSize(entries: ResizeObserverEntry[]) {
 }
 
 /**
+ * Manually dispatches an event through the custom event system.
+ * Simulates bubbling unless the event type is in the unbubbleEvents list.
  * 
+ * @param ev - The event to dispatch.
  */
 
 export function dispatchEvent(ev: Event) {
@@ -129,7 +132,14 @@ export function dispatchEvent(ev: Event) {
 }
 
 /**
+ * Registers an event handler for a specific node.
+ * Automatically initializes MutationObserver or ResizeObserver if special events 
+ * ('created', 'removed', 'resized') are requested.
  * 
+ * @param node - The target DOM node.
+ * @param name - The name of the event to listen for.
+ * @param handler - The function to call when the event occurs.
+ * @param prepend - Whether to prepend the handler to the list (default: false).
  */
 
 export function addEvent( node: Node, name: string, handler: DOMEventHandler, prepend = false ) {

package/src/core/core_dragdrop.ts

@@ -27,8 +27,10 @@ interface DropInfo {
 type DropCallback = ( command: 'enter' | 'leave' | 'drag' | 'drop', el: Component, infos: DropInfo ) => void;
 type FilterCallback = ( el: Component, data: DataTransfer ) => boolean;
 
-/**
- * 
+/** 
+ * Manages drag and drop operations within the application.
+ * This class handles the registration of draggable elements and drop targets, 
+ * and orchestrates the visual feedback and event dispatching during drag operations.
  */
 
 
@@ -43,9 +45,13 @@ class DragManager {
 	timer: any; // pb with name of settimeout return
 
 	/**
-	 * 
+	 * Registers a component as a draggable element.
+	 * This sets up DOM event listeners for `dragstart`, `drag`, and `dragend`
+	 * to manage the drag operation, including creating a drag ghost and applying CSS classes.
+	 *
+	 * @param el - The component to make draggable.
 	 */
-
+	// TODO: Add support for custom drag data beyond 'text/string'.
 	registerDraggableElement(el: Component) {
 
 		el.addDOMEvent('dragstart', (ev: DragEvent) => {
@@ -78,7 +84,14 @@ class DragManager {
 	}
 
 	/**
-	 * 
+	 * Registers a component as a drop target.
+	 * This sets up DOM event listeners for `dragenter`, `dragover`, `dragleave`, and `drop`.
+	 * It uses a `DropCallback` to notify the component about drag events and an optional `FilterCallback`
+	 * to determine if the target should accept the dragged item.
+	 *
+	 * @param el - The component to make a drop target.
+	 * @param cb - The callback function to execute on drag events.
+	 * @param filterCB - An optional callback to filter which draggable items can be dropped.
 	 */
 
 	registerDropTarget(el: Component, cb: DropCallback, filterCB?: FilterCallback ) {
@@ -151,7 +164,11 @@ class DragManager {
 		el.setInternalData( x_drag_cb, cb );
 	}
 
-	_startCheck() {
+	/**
+	 * @internal
+	 */
+
+	private _startCheck() {
 
 		if (this.timer) {
 			clearInterval(this.timer);
@@ -161,7 +178,11 @@ class DragManager {
 		this.timer = setInterval( () => this._check(), 300 );
 	}
 
-	_check( ) {
+	/**
+	 * @internal
+	 */
+
+	private _check( ) {
 
 		const leaving = ( x: Component ) => {
 			x.removeClass('drop-over');
@@ -198,4 +219,8 @@ class DragManager {
 	}
 }
 
+/**
+ * Singleton instance of the DragManager for global access.
+ */
+
 export const dragManager = new DragManager();

package/src/core/core_element.ts

@@ -16,10 +16,67 @@
 
 import { EventMap, EventSource } from './core_events';
 
+
 /**
- * 
+ * CoreElement
+ *
+ * A lightweight base class that provides two orthogonal utilities commonly needed by UI
+ * or domain objects:
+ * 1) Named timers (wraps setTimeout / setInterval by name so they can be started, stopped,
+ *    and cleared by string identifier), and
+ * 2) A typed eventing surface (lazy-initialised EventSource) for attaching, detaching and
+ *    firing events.
+ *
+ * The class is generic over an EventMap `E` which maps event name keys to the payload
+ * type for that event. This enables compile-time type safety for listeners and fired events.
+ *
+ * Template parameters:
+ * @template E - An {@link EventMap}-shaped type that maps event keys to the event payload types.
+ *
+ * Timer semantics:
+ * - Timers are referenced by a string `name`. Each instance of CoreElement maintains its own
+ *   map of timers.
+ * - Starting a timer with a name that is already present will stop the previous timer first.
+ * - setTimeout(name, ms, callback) creates a single-shot timer (uses global setTimeout).
+ * - setInterval(name, ms, callback) creates a repeating timer (uses global setInterval).
+ * - clearTimeout(name) and clearInterval(name) both stop and remove the timer with the given
+ *   name (they are aliases for the same internal stop logic).
+ * - clearTimeouts() will stop and remove all timers currently tracked by the instance.
+ * - The underlying timer handles are encapsulated; callers only interact via the string name.
+ *
+ * Event semantics:
+ * - Event support is provided via a lazily-initialised EventSource instance internal to the
+ *   CoreElement. The EventSource is created on first use (first call to on()).
+ * - on(name, listener) registers a listener for the given event name and returns a small
+ *   subscription object exposing an off() method for convenience.
+ * - off(name, listener) removes a previously-registered listener (no-op if there is no
+ *   EventSource or listener).
+ * - fire(name, ev) will dispatch the given payload to all listeners registered for that
+ *   event name (no-op if there is no EventSource).
+ * - Listener and event payload types are enforced by the generic `E`.
+ *
+ * Threading / reentrancy / error handling:
+ * - Timer callbacks execute via the platform timer mechanisms (setTimeout/setInterval). Any
+ *   exceptions thrown by callbacks will propagate according to the environment's timer
+ *   semantics (typically uncaught unless handled by the callback).
+ * - The class uses console.assert to validate non-null listeners on public attach/detach
+ *   methods; callers should avoid passing undefined/null listeners.
+ * Example:
+ * ```ts
+ * // Strongly-typed events
+ * interface MyEvents { loaded: { ok: boolean }, tick: number }
+ * class MyElement extends CoreElement<MyEvents> {}
+ *
+ * const el = new MyElement();
+ * const sub = el.on("loaded", e => console.log(e.ok));
+ * el.fire("loaded", { ok: true });
+ * sub.off(); // convenience to remove listener
+ *
+ * // Timers
+ * el.setInterval("poll", 1000, () => el.fire("tick", Date.now()));
+ * el.clearInterval("poll");
+ * ```
  */
-
 export class CoreElement<E extends EventMap = EventMap> {
 
 	#events: EventSource<E>;
@@ -46,22 +103,55 @@ export class CoreElement<E extends EventMap = EventMap> {
 		if (clear) { clear(); }
 	}
 
+	/**
+	 * Sets a timeout that executes a callback function after a specified delay.
+	 * If a timeout with the same name already exists, it will be cleared before the new one is set.
+	 * @param name - A unique string identifier for this timeout.
+	 * @param ms - The delay in milliseconds before the callback is executed.
+	 * @param callback - The function to execute after the delay.
+	 */
+	
 	setTimeout( name: string, ms: number, callback: () => void ) {
 		this.__startTimer( name, ms, false, callback );
 	}
+	
+	/**
+	 * Clears a previously set timeout.
+	 * @param name - The name of the timeout to clear.
+	 * @link setTimeout
+	 */
 
 	clearTimeout( name: string ) {
 		this.__stopTimer( name );
 	}
 
+	/**
+	 * Sets an interval that repeatedly executes a callback function after a specified delay.
+	 * If a timeout with the same name already exists, it will be cleared before the new one is set.
+	 * @param name - A unique string identifier for this timeout.
+	 * @param ms - The delay in milliseconds before the callback is executed.
+	 * @param callback - The function to execute after the delay.
+	 */
+
 	setInterval( name: string, ms: number, callback: ( ) => void ) {
 		this.__startTimer( name, ms, true, callback );
 	}
 
+	/**
+	 * Clears a previously set interval.
+	 * @param name - The name of the interval to clear.
+	 * @link setInterval
+	 */
+
 	clearInterval( name: string ) {
 		this.__stopTimer( name );
 	}
 
+	/**
+	 * Clears all timeouts and intervals currently managed by this instance.
+	 * This stops all scheduled callbacks and removes their references.
+	 * @link setTimeout
+	 */
 	clearTimeouts( ) {
 		for( const [id,val] of this.#timers ) {
 			val( );
@@ -73,6 +163,13 @@ export class CoreElement<E extends EventMap = EventMap> {
 	// :: EVENTS ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 	/**
+	 * Registers an event listener for a specific event name.
+	 * The listener will be invoked when an event with the given name is fired.
+	 * Returns an object with an `off()` method, which can be used to conveniently remove this specific listener.
+	 * @param name - The name of the event to listen for.
+	 * @param listener - The callback function to execute when the event is fired.
+	 * @returns An object containing an `off()` method to unsubscribe the listener.
+	 * @link fire
 	 * attach to an event
 	 */
 
@@ -92,7 +189,12 @@ export class CoreElement<E extends EventMap = EventMap> {
 	}
 
 	/**
-	 * detach
+	 * Removes a previously registered event listener.
+	 * If the listener was not found or no events were registered, this method does nothing.
+	 * @param name - The name of the event from which to remove the listener.
+	 * @param listener - The specific listener function to remove.
+	 * @link on
+	 * @link fire
 	 */
 
 	off<K extends keyof E>( name: K, listener: ( ev: E[K] ) => void ) {
@@ -104,7 +206,12 @@ export class CoreElement<E extends EventMap = EventMap> {
 	}
 
 	/**
-	 * 
+	 * Dispatches an event with a given name and payload to all registered listeners.
+	 * If no listeners are registered for the event name, or if no EventSource has been initialized, this method does nothing.
+	 * @param name - The name of the event to fire.
+	 * @param ev - The payload (event object) to pass to the listeners.
+	 * @link on
+	 * @link off
 	 */
 
 	fire<K extends keyof E>( name: K, ev: E[K] ) {

package/src/core/core_events.ts

@@ -17,7 +17,9 @@
 import { CoreElement } from './core_element';
 
 /**
- * 
+ * Represents a base event interface for the framework.
+ * All custom events should implement this interface to ensure consistent behavior
+ * regarding event propagation and default action prevention.
  */
 
 export interface CoreEvent {
@@ -28,7 +30,15 @@ export interface CoreEvent {
 	propagationStopped?: boolean;	// if true, do not propagate the event
 	defaultPrevented?: boolean;		// if true, do not call default handler (if any)
 
+	/**
+	 * Stops the propagation of the event to further listeners.
+	 * Subsequent listeners for the same event on the same EventSource will not be called.
+	 */
 	stopPropagation?(): void;		// stop the propagation
+	/**
+	 * Prevents the default action associated with the event.
+	 * If a default handler exists, it will not be executed.
+	 */
 	preventDefault?(): void;		// prevent the default handler
 }
 
@@ -44,20 +54,35 @@ const preventDefault = function ( this: CoreEvent ) {
 
 
 /**
- * 
+ * A generic interface for mapping event names to their corresponding event payload types.
+ * This is used by `EventSource` and `CoreElement` to provide compile-time type safety
+ * for event listeners and fired events.
+ *
+ * @example
+ * ```typescript
+ * interface MyCustomEvents {
+ *   'dataLoaded': { data: any, timestamp: number };
+ *   'itemSelected': { itemId: string };
+ * }
+ * ```
  */
 
 export interface EventMap {
 }
 
 /**
- * 
+ * Defines the signature for an event callback function.
+ * @template T - The specific type of `CoreEvent` that the callback handles.
  */
 
 export type EventCallback<T extends CoreEvent = CoreEvent> = (event: T) => any;
 
 /**
- * 
+ * A base class for objects that can emit and listen to custom events.
+ * It provides a typed eventing mechanism, allowing for the registration and removal of listeners,
+ * and the firing of events with associated payloads.
+ *
+ * @template E - An `EventMap`-shaped type that defines the events supported by this source.
  */
 
 export class EventSource<E extends EventMap = EventMap > {
@@ -65,10 +90,21 @@ export class EventSource<E extends EventMap = EventMap > {
 	private _source: unknown;
 	private _registry: Map<string,EventCallback[]>;
 
+	/**
+	 * Creates an instance of EventSource.
+	 * @param source - The object that will be reported as the `source` of events fired by this instance.
+	 *                 If `null` or `undefined`, the `EventSource` instance itself will be the source.
+	 */
 	constructor(source: unknown = null) {
 		this._source = source ?? this;
 	}
 
+	/**
+	 * Registers an event listener for a specific event name.
+	 * @param name - The name of the event to listen for (must be a key in `E`).
+	 * @param callback - The function to be called when the event is fired.
+	 * @param capturing - If `true`, the listener will be added to the beginning of the listener list (capturing phase).
+	 */
 	addListener<K extends keyof E>( name: K, callback: ( ev: E[K] ) => void, capturing = false ) {
 		
 		if (!this._registry) {
@@ -98,9 +134,9 @@ export class EventSource<E extends EventMap = EventMap > {
 	}
 
 	/**
-	 * stop listening to an event
-	 * @param eventName - event name
-	 * @param callback - callback to remove (must be the same as in on )
+	 * Removes a previously registered event listener.
+	 * @param name - The name of the event from which to remove the listener.
+	 * @param callback - The specific callback function to remove. It must be the same function instance that was originally registered.
 	 */
 
 	removeListener<K extends keyof E>(name: K, callback: (ev: E[K]) => any) {
@@ -121,6 +157,11 @@ export class EventSource<E extends EventMap = EventMap > {
 		}
 	}
 
+	/**
+	 * Dispatches an event with a given name and payload to all registered listeners.
+	 * @param name - The name of the event to fire (must be a key in `E`).
+	 * @param evx - The event payload (event object) to pass to the listeners.
+	 */
 	fire<K extends keyof E>(name: K, evx: E[K]) {
 		
 		let listeners = this._registry?.get(name as string);
@@ -171,7 +212,3 @@ export class EventSource<E extends EventMap = EventMap > {
 		//}
 	}
 }
-
-
-
-

package/src/core/core_i18n.ts

@@ -289,6 +289,7 @@ let fr = {
 
 		date_input_formats: 'd/m/y|d.m.y|d m y|d-m-y|dmy',
 		date_format: 'D/M/Y',
+        date_time_format: 'D/M/Y H:I:S',
 
 		day_short: [ 'dim', 'lun', 'mar', 'mer', 'jeu', 'ven', 'sam' ],
 		day_long: [ 'dimanche', 'lundi', 'mardi', 'mercredi', 'jeudi', 'vendredi', 'samedi' ],
@@ -353,6 +354,7 @@ let en = {
 
 		date_input_formats: 'm/d/y|m.d.y|m d y|m-d-y|mdy',
 		date_format: 'M/D/Y',
+        date_time_format: 'M/D/Y H:I:S',
 
 		day_short: [ 'sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat' ],
 		day_long: [ 'sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday' ],