x4js 2.3.17 → 2.3.18

package/src/core/core_clipboard.ts

@@ -0,0 +1,239 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file core_clipboard.ts
+ * @author Etienne Cochard
+ *
+ * @copyright (c) 2026 R-libre ingenierie
+ *
+ * Use of this source code is governed by an MIT-style license
+ * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
+ **/
+
+/**
+ * The clipboard of the system: a text, an image, files.
+ *
+ * There are two ways to it, and they do not give the same things.
+ *
+ * In a "copy", "cut" or "paste" event (the keys of the user, the menu of
+ * the browser), the browser gives its clipboard at once and asks nothing:
+ * setEventClipboard, getEventClipboard. It is the only way to read files.
+ *
+ * Out of an event (a menu, a button), the system is asked: setClipboard,
+ * getClipboard. It is asynchronous, the browser may ask the user for a
+ * permission or refuse, and there is nothing to ask on a page that is not
+ * served in https. So what the application set last is kept: it is what is
+ * read when the system does not answer, and copy and paste still work
+ * inside the application.
+ *
+ * Files cannot be written, in neither way.
+ */
+
+export interface ClipboardContent {
+	text?: string;
+	/** written as a PNG, the format every browser takes: another one is converted */
+	image?: Blob;
+}
+
+export interface ClipboardRead extends ClipboardContent {
+	/** all the files, the images too; none out of an event */
+	files: File[];
+}
+
+/** what the application set last */
+let kept: ClipboardContent = null;
+
+function toPng( image: Blob ): Promise<Blob> {
+	return new Promise( ( resolve, reject ) => {
+		const url = URL.createObjectURL( image );
+		const img = document.createElement( "img" );
+
+		img.onload = ( ) => {
+			URL.revokeObjectURL( url );
+
+			const canvas = document.createElement( "canvas" );
+			canvas.width = img.naturalWidth;
+			canvas.height = img.naturalHeight;
+			canvas.getContext( "2d" ).drawImage( img, 0, 0 );
+
+			canvas.toBlob( png => png ? resolve( png ) : reject( new Error( "not an image" ) ), "image/png" );
+		};
+
+		img.onerror = ( ) => {
+			URL.revokeObjectURL( url );
+			reject( new Error( "not an image" ) );
+		};
+
+		img.src = url;
+	} );
+}
+
+/**
+ * Set the clipboard, from a menu or a button.
+ *
+ * @returns true when the system took it. When it did not, getClipboard
+ * still gives it back: it can be pasted in the application.
+ *
+ * @example
+ * setClipboard( { text: "hello" } );
+ * setClipboard( { image: blob, text: "the same, for what cannot paste an image" } );
+ */
+
+export async function setClipboard( data: ClipboardContent ): Promise<boolean> {
+	kept = { text: data.text, image: data.image };
+
+	// not there on a page that is not served in https
+	const system = navigator.clipboard;
+	if( !system ) {
+		return false;
+	}
+
+	try {
+		if( !data.image ) {
+			await system.writeText( data.text ?? "" );
+			return true;
+		}
+
+		// the conversion is given as a promise: the system has to be asked
+		// now, while the click of the user still allows it
+		const parts: Record<string,Blob | Promise<Blob>> = {
+			"image/png": data.image.type==="image/png" ? data.image : toPng( data.image ),
+		};
+
+		if( data.text ) {
+			parts["text/plain"] = new Blob( [data.text], { type: "text/plain" } );
+		}
+
+		await system.write( [new ClipboardItem( parts )] );
+		return true;
+	}
+	catch( e ) {
+		return false;
+	}
+}
+
+/**
+ * Read the clipboard, from a menu or a button.
+ *
+ * @returns what the system holds. When it refuses or cannot be asked, what
+ * the application set last. Never files: see getEventClipboard.
+ *
+ * @example
+ * const data = await getClipboard( );
+ * if( data.text ) {
+ * 	input.setValue( data.text );
+ * }
+ */
+
+export async function getClipboard( ): Promise<ClipboardRead> {
+	const system = navigator.clipboard;
+
+	if( system ) {
+		try {
+			// read gives the images too, but some browsers only have readText
+			if( !system.read ) {
+				const text = await system.readText( );
+				return { text: text || undefined, files: [] };
+			}
+
+			const data: ClipboardRead = { files: [] };
+
+			for( const item of await system.read( ) ) {
+				for( const type of item.types ) {
+					if( type==="text/plain" && !data.text ) {
+						const blob = await item.getType( type );
+						data.text = ( await blob.text( ) ) || undefined;
+					}
+					else if( type.startsWith( "image/" ) && !data.image ) {
+						data.image = await item.getType( type );
+					}
+				}
+			}
+
+			return data;
+		}
+		catch( e ) {
+			// refused: what the application has
+		}
+	}
+
+	if( kept ) {
+		return { text: kept.text, image: kept.image, files: [] };
+	}
+
+	return { files: [] };
+}
+
+/**
+ * false when getClipboard has nothing to give: the system cannot be asked,
+ * and the application did not set anything. What the system holds is not
+ * known before it is asked for.
+ *
+ * @example
+ * { text: _tr.global.paste, disabled: !canReadClipboard( ), click: ( ) => this.paste( ) }
+ */
+
+export function canReadClipboard( ): boolean {
+	const system = navigator.clipboard;
+	if( system && ( system.read || system.readText ) ) {
+		return true;
+	}
+
+	return !!kept;
+}
+
+/**
+ * Set the clipboard in a "copy" or a "cut" event. The default of the event
+ * is prevented: the browser would copy its own selection instead.
+ *
+ * @example
+ * this.addDOMEvent( "copy", ev => {
+ * 	setEventClipboard( ev, { text: this.getSelectedText( ) } );
+ * } );
+ */
+
+export function setEventClipboard( ev: ClipboardEvent, data: ClipboardContent ): void {
+	kept = { text: data.text, image: data.image };
+
+	ev.preventDefault( );
+
+	if( data.text!==undefined && ev.clipboardData ) {
+		ev.clipboardData.setData( "text/plain", data.text );
+	}
+
+	// the event only takes texts: the image is given to the system
+	if( data.image ) {
+		setClipboard( data );
+	}
+}
+
+/**
+ * Read the clipboard in a "paste" event. The default of the event is left
+ * as it is: prevent it when what was read is used.
+ *
+ * @example
+ * this.addDOMEvent( "paste", ev => {
+ * 	const data = getEventClipboard( ev );
+ * 	if( data.image ) {
+ * 		ev.preventDefault( );
+ * 		this.setPicture( data.image );
+ * 	}
+ * } );
+ */
+
+export function getEventClipboard( ev: ClipboardEvent ): ClipboardRead {
+	const data: ClipboardRead = { files: [] };
+
+	const transfer = ev.clipboardData;
+	if( transfer ) {
+		data.text = transfer.getData( "text/plain" ) || undefined;
+		data.files = Array.from( transfer.files );
+		data.image = data.files.find( file => file.type.startsWith( "image/" ) );
+	}
+
+	return data;
+}

package/src/core/core_data.ts

@@ -1152,41 +1152,72 @@ export class DataView extends CoreElement<DataViewEventMap>
 
 	protected m_props: DataViewProps;
 
+	private m_unlink: ( ) => void;	// stops listening to the store
+
 	constructor( props: DataViewProps ) {
 		super( );
 
 		this.m_props = props;
 		this.m_store = props.store;
 		this.m_index = null;
-		this.m_filter = null;
-		this.m_sort = null;
 		this.m_model = this.m_store.getModel();
+		this.m_filter = props.filter;
 
-		this.filter( props.filter );
-		
-		if( props.order ) {
-			if( isString(props.order) ) {
-				this.sort( [ { field: props.order, ascending: true } ] );
-			}
-			else if( isArray(props.order) ) {
-				this.sort( props.order );
-			}
-			else {
-				this.sort( [props.order] );
-			}
+		if( !props.order ) {
+			this.m_sort = null;
+		}
+		else if( isString(props.order) ) {
+			this.m_sort = [ { field: props.order, ascending: true } ];
+		}
+		else if( isArray(props.order) ) {
+			this.m_sort = props.order;
 		}
 		else {
-			this.sort( null );
+			this.m_sort = [props.order];
 		}
 
-		this.m_store.addListener( 'data_change', ( e ) => this._storeChange(e) );
+		// listens to the store, then filters and sorts
+		this.open( );
 	}
 
-	private _storeChange( ev: EvDataChange ) {
-		
-		this._filter( this.m_filter, ev.type!='change' );
-		this._sort( this.m_sort, ev.type!='change' );
-		
+	/**
+	 * The view follows its store: it is filtered and sorted with what the
+	 * store holds now, and again at each of its changes.
+	 * Called when the view is made, and to use it again after a close( ).
+	 */
+
+	open( ) {
+		if( this.m_unlink ) {
+			return;
+		}
+
+		this.m_unlink = this.m_store.addListener( 'data_change', ( ) => this._storeChange( ) );
+		this._storeChange( );
+	}
+
+	/**
+	 * The view stops following its store, until open( ) is called.
+	 * A store keeps every view that listens to it: without this, a view
+	 * that is not used anymore would still be filtered, sorted and heard at
+	 * each change.
+	 */
+
+	close( ) {
+		if( this.m_unlink ) {
+			this.m_unlink( );
+			this.m_unlink = null;
+		}
+	}
+
+	private _storeChange( ) {
+
+		// filtered and sorted again without telling: the event that follows says it all.
+		// _filter sorts when the view is sorted; when it is not, it is by id
+		this._filter( this.m_filter, false );
+		if( !this.m_sort ) {
+			this._sort( null, false );
+		}
+
 		this.fire( 'view_change', { change_type: 'change' } );
 	}
 
@@ -1206,9 +1237,9 @@ export class DataView extends CoreElement<DataViewEventMap>
 		this.m_index = this.m_store.createIndex( filter );
 		this.m_filter = filter;
 
-		// need to sort again:
+		// need to sort again, without telling: the filter is what changed
 		if( this.m_sort ) {
-			this.sort( this.m_sort );
+			this._sort( this.m_sort, false );
 		}
 		
 		if( notify ) {

package/src/core/core_dom.ts

@@ -19,7 +19,7 @@ export const COMPONENT = Symbol( "component" );
 /** @ignore this events must be defined on domNode (do not bubble) */
 export const unbubbleEvents = {
 	mouseleave: 1, mouseenter: 1, load: 1, unload: 1, scroll: 1, focus: 1, blur: 1, rowexit: 1, beforeunload: 1, stop: 1,
-	dragdrop: 1, dragenter: 1, dragexit: 1, draggesture: 1, dragover: 1, contextmenu: 1, created: 2, removed: 2, sizechange: 2
+	dragdrop: 1, dragenter: 1, dragexit: 1, draggesture: 1, dragover: 1, contextmenu: 1, created: 2, removed: 2, resized: 2
 };
 
 export type DOMEventHandler = ( ev: Event ) => void;
@@ -118,8 +118,12 @@ function observeSize(entries: ResizeObserverEntry[]) {
 
 export function dispatchEvent(ev: Event) {
 
-	let target = ev.target as Node,
-		noup = (unbubbleEvents as any)[ev.type] === 2;
+	// 2: an event of x4, for its node only.
+	// 1: stops at its node when the browser does not bubble it (focus, mouseenter...)
+	const flag = (unbubbleEvents as any)[ev.type];
+	const noup = flag===2 || ( flag===1 && !ev.bubbles );
+
+	let target = ev.target as Node;
 
 	while (target) {
 		const store = event_handlers.get( target );
@@ -127,8 +131,11 @@ export function dispatchEvent(ev: Event) {
 			const callback = store[ev.type];
 			if( callback ) {
 				if( Array.isArray(callback) ) {
-					callback.some( c => c( ev ) );
-				}	
+					// a handler that returns true stops those that follow it on this node.
+					// true only: an arrow function returns what its expression does
+					// (ev => this.show( ) returns this), and this must stop nothing
+					callback.some( c => (c( ev ) as any)===true );
+				}
 				else {
 					callback( ev );
 				}
@@ -255,7 +262,17 @@ export interface GlobalDOMEvents {
 	 * @param ev The mouse event.
 	 */
 	contextmenu?: (ev: MouseEvent) => any;
+	/**
+	 * Fires when the user copies (the keys, or the menu of the browser).
+	 * @param ev The clipboard event: see setEventClipboard.
+	 */
+	copy?: (ev: ClipboardEvent) => any;
 	cuechange?: (ev: Event) => any;
+	/**
+	 * Fires when the user cuts.
+	 * @param ev The clipboard event: see setEventClipboard.
+	 */
+	cut?: (ev: ClipboardEvent) => any;
 	/**
 	 * Fires when the user double-clicks the object.
 	 * @param ev The mouse event.
@@ -391,6 +408,11 @@ export interface GlobalDOMEvents {
 	 * @param ev The event.
 	 */
 	pause?: (ev: Event) => any;
+	/**
+	 * Fires when the user pastes.
+	 * @param ev The clipboard event: see getEventClipboard.
+	 */
+	paste?: (ev: ClipboardEvent) => any;
 	/**
 	 * Occurs when the play method is requested.
 	 * @param ev The event.

package/src/core/core_dragdrop.ts

@@ -19,13 +19,13 @@ import { Point } from './core_tools';
 
 const x_drag_cb = Symbol( 'x-drag-cb' );
 
-interface DropInfo {
+export interface DropInfo {
 	pt: Point;
 	data: DataTransfer;
 }
 
-type DropCallback = ( command: 'enter' | 'leave' | 'drag' | 'drop', el: Component, infos: DropInfo ) => void;
-type FilterCallback = ( el: Component, data: DataTransfer ) => boolean;
+export type DropCallback = ( command: 'enter' | 'leave' | 'drag' | 'drop', el: Component, infos: DropInfo ) => void;
+export type DropFilterCallback = ( el: Component, data: DataTransfer ) => boolean;
 
 /** 
  * Manages drag and drop operations within the application.
@@ -78,6 +78,12 @@ class DragManager {
 		el.addDOMEvent('dragend', (ev: DragEvent) => {
 			el.removeClass( 'dragging' );
 			this.dragGhost.remove();
+
+			// the target that was left is told now, while the source is known.
+			// Then the source is forgotten: the next drag may be one of files
+			// that come from the desktop, which has none
+			this._check( );
+			this.dragSource = null;
 		});
 
 		el.setAttribute('draggable', "true");
@@ -86,7 +92,7 @@ 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`
+	 * It uses a `DropCallback` to notify the component about drag events and an optional `DropFilterCallback`
 	 * to determine if the target should accept the dragged item.
 	 *
 	 * @param el - The component to make a drop target.
@@ -94,7 +100,7 @@ class DragManager {
 	 * @param filterCB - An optional callback to filter which draggable items can be dropped.
 	 */
 
-	registerDropTarget(el: Component, cb: DropCallback, filterCB?: FilterCallback ) {
+	registerDropTarget(el: Component, cb: DropCallback, filterCB?: DropFilterCallback ) {
 
 		const dragEnter = (ev: DragEvent) => {
 			if( filterCB && !filterCB(this.dragSource,ev.dataTransfer) ) {

package/src/core/core_element.ts

@@ -232,7 +232,7 @@ export class CoreElement<E extends EventMap = EventMap> {
 			return;
 		}
 
-		// Entries no longer mutate the map in clear(), so plain iteration is safe.
+		// clear() of an entry does not touch the map, so plain iteration is safe.
 		for (const entry of this.#timers.values()) {
 			entry.clear();
 		}

package/src/core/core_shortcuts.ts

@@ -51,7 +51,7 @@ interface Keys {
 	key: string;
 }
 
-const isMac = typeof navigator!=="undefined" && /mac|iphone|ipad/i.test( navigator.platform ?? "" );
+const isMac = /mac|iphone|ipad/i.test( navigator.platform ?? "" );
 
 /**
  * "Shift+Mod+K" -> shift, ctrl (cmd on a Mac), k

package/src/x4.d.ts

@@ -15,6 +15,7 @@
  **/
 export * from "./core/component";
 export * from "./core/core_application";
+export * from "./core/core_clipboard";
 export * from "./core/core_colors";
 export * from "./core/core_data";
 export * from "./core/core_dom";

package/src/x4.ts

@@ -16,6 +16,7 @@
 
 export * from "./core/component"
 export * from "./core/core_application"
+export * from "./core/core_clipboard"
 export * from "./core/core_colors"
 export * from "./core/core_data"
 export * from "./core/core_dom"