x4js 2.3.13 → 2.3.15

package/src/core/core_application.ts

@@ -18,6 +18,7 @@ import { Component, componentFromDOM } from './component';
 import { CoreElement } from './core_element';
 import { CoreEvent, EventMap } from './core_events';
 import { asap, getFocusableElements, ITabHandler } from './core_tools';
+import { Shortcuts, ShortcutCallback, ShortcutOptions } from './core_shortcuts';
 
 const socket_sent = Symbol( 'socket' );
 
@@ -80,6 +81,9 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
 	private mainview: Component;
 	private props: AppProps;
 	private mounted = false;
+
+	private _shortcuts = new Shortcuts( );
+	private _active: { owner: Component, shortcuts: Shortcuts };
 	
 	 /**
      * Provides access to process-related information, such as touch capabilities.
@@ -206,9 +210,38 @@ export class Application<E extends ApplicationEvents = ApplicationEvents> extend
 					ev.preventDefault( );
 				}
 			}
+
+			// The focus is nowhere: the shortcuts of the view the user worked in last.
+			// (when it is in a view, the view has seen the key before us)
+			if( ev.target===document.body && this._active?.owner.dom.isConnected && this._active.shortcuts.handle( ev ) ) {
+				return;
+			}
+
+			this._shortcuts.handle( ev );
 		} );
 	}
 
+	/**
+	 * Adds a keyboard shortcut to the whole application: it works wherever
+	 * the focus is, even in a dialog. A key typed in a field is not a
+	 * shortcut, unless `editable` is set.
+	 *
+	 * @param keys - "Mod+S", "F1"... or several of them. Mod is Ctrl, or Cmd on a Mac.
+	 * @see Component.addShortcut for the shortcuts of a view
+	 */
+
+	addShortcut( keys: string | string[], callback: ShortcutCallback, options?: ShortcutOptions ) {
+		this._shortcuts.add( keys, callback, options );
+	}
+
+	/**
+	 * @internal the last component with shortcuts that had the focus
+	 */
+
+	setActiveShortcuts( owner: Component, shortcuts: Shortcuts ) {
+		this._active = { owner, shortcuts };
+	}
+
 	/**
      * Moves focus to the next or previous focusable element within the application.
      * Handles Tab and Shift+Tab key presses.

package/src/core/core_shortcuts.ts

@@ -0,0 +1,181 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file core_shortcuts.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.
+ **/
+
+import { isArray } from './core_tools';
+
+/**
+ * Keyboard shortcuts.
+ *
+ * A shortcut is a sequence of keys, written as it is read: "Mod+C",
+ * "Shift+Mod+Z", "Delete", "Alt+ArrowLeft". The modifiers are Shift, Ctrl,
+ * Cmd, Alt and Mod: the key of the commands, which is Ctrl on Windows and
+ * Linux, and Cmd on a Mac.
+ *
+ * This class only holds a list of shortcuts and finds the one a keyboard
+ * event is. It is used by Component.addShortcut (the shortcuts of a view,
+ * while the focus is in it) and by Application.addShortcut (those of the
+ * whole application).
+ */
+
+export type ShortcutCallback = ( ev: KeyboardEvent ) => void;
+
+export interface ShortcutOptions {
+	/** also while the user types in a field (Mod+S, F5...) */
+	editable?: boolean;
+}
+
+interface Shortcut {
+	sequence: string;
+	callback: ShortcutCallback;
+	editable: boolean;
+}
+
+interface Keys {
+	shift: boolean;
+	ctrl: boolean;
+	cmd: boolean;
+	alt: boolean;
+	key: string;
+}
+
+const isMac = typeof navigator!=="undefined" && /mac|iphone|ipad/i.test( navigator.platform ?? "" );
+
+/**
+ * "Shift+Mod+K" -> shift, ctrl (cmd on a Mac), k
+ */
+
+function parse( keys: string ): Keys {
+	const parts = keys.toLowerCase( ).split( "+" ).map( p => p.trim( ) );
+	const key = parts.pop( ) || "+";			// "Ctrl++": the key is +
+	const has = ( name: string ) => parts.includes( name );
+
+	return {
+		shift: has( "shift" ),
+		ctrl: has( "ctrl" ) || ( has( "mod" ) && !isMac ),
+		cmd: has( "cmd" ) || ( has( "mod" ) && isMac ),
+		alt: has( "alt" ),
+		key
+	};
+}
+
+/**
+ * always in the same order: "shift+ctrl+cmd+alt+key"
+ */
+
+function join( k: Keys ): string {
+	return ( k.shift ? "shift+" : "" ) + ( k.ctrl ? "ctrl+" : "" ) + ( k.cmd ? "cmd+" : "" ) + ( k.alt ? "alt+" : "" ) + k.key;
+}
+
+function sequenceOf( ev: KeyboardEvent ): string {
+	// AltGr writes characters, never a command (Windows reports it as ctrl + alt)
+	if( ev.getModifierState( "AltGraph" ) ) {
+		return null;
+	}
+
+	// a keyboard without latin letters: the key where the letter is on a latin one
+	let key = ev.key.toLowerCase( );
+	if( key.length===1 && ( key<"a" || key>"z" ) && /^Key[A-Z]$/.test( ev.code ) ) {
+		key = ev.code[3].toLowerCase( );
+	}
+
+	return join( { shift: ev.shiftKey, ctrl: ev.ctrlKey, cmd: ev.metaKey, alt: ev.altKey, key } );
+}
+
+function isEditable( target: EventTarget ): boolean {
+	const el = target as HTMLElement;
+	return el.isContentEditable || el.tagName==="INPUT" || el.tagName==="TEXTAREA" || el.tagName==="SELECT";
+}
+
+/**
+ *
+ */
+
+export class Shortcuts {
+
+	private list: Shortcut[] = [];
+
+	/**
+	 * @param keys - a sequence, or several ones for the same action
+	 * @example
+	 * shortcuts.add( "Mod+C", ( ) => this.copy( ) );
+	 * shortcuts.add( ["Mod+Y", "Shift+Mod+Z"], ( ) => this.redo( ) );
+	 */
+
+	add( keys: string | string[], callback: ShortcutCallback, options: ShortcutOptions = {} ) {
+		for( const k of isArray( keys ) ? keys : [keys] ) {
+			this.list.push( { sequence: join( parse( k ) ), callback, editable: !!options.editable } );
+		}
+	}
+
+	clear( ) {
+		this.list = [];
+	}
+
+	/**
+	 * calls the shortcut a key is, if any
+	 * @returns true when it was one
+	 */
+
+	handle( ev: KeyboardEvent ): boolean {
+		// already used by what has the focus (Enter on a button...)
+		if( ev.defaultPrevented ) {
+			return false;
+		}
+
+		const sequence = sequenceOf( ev );
+		const found = this.list.find( s => s.sequence===sequence && ( s.editable || !isEditable( ev.target ) ) );
+		if( !found ) {
+			return false;
+		}
+
+		ev.preventDefault( );
+		found.callback( ev );
+		return true;
+	}
+}
+
+/**
+ * how the keys with a name are written
+ */
+
+const key_names: Record<string,string> = {
+	arrowleft: "←",
+	arrowup: "↑",
+	arrowright: "→",
+	arrowdown: "↓",
+	escape: "Esc",
+	delete: "Del",
+	" ": "Space",
+};
+
+/**
+ * How a sequence is written for the user, in a tooltip or a menu:
+ * "Ctrl+C", "Ctrl+Shift+Z", and on a Mac the signs of its keys.
+ *
+ * @example
+ * new Button( { icon, tooltip: `Undo (${shortcutText( "Mod+Z" )})` } )
+ */
+
+export function shortcutText( keys: string ): string {
+	const k = parse( keys );
+	const key = key_names[k.key] ?? ( k.key[0].toUpperCase( ) + k.key.substring( 1 ) );
+
+	if( isMac ) {
+		return ( k.ctrl ? "⌃" : "" ) + ( k.alt ? "⌥" : "" ) + ( k.shift ? "⇧" : "" ) + ( k.cmd ? "⌘" : "" ) + key;
+	}
+
+	return ( k.ctrl ? "Ctrl+" : "" ) + ( k.cmd ? "Meta+" : "" ) + ( k.alt ? "Alt+" : "" ) + ( k.shift ? "Shift+" : "" ) + key;
+}

package/src/core/core_state.ts

@@ -139,9 +139,13 @@ export class StateManager<T extends State> extends EventSource<StateEvents> {
 					return Reflect.get( target, prop, receiver );
 				}
 
-				// genuinely missing property ('in' walks the prototype chain, so array methods, toString, toJSON... never trigger a false positive)
+				// genuinely missing property ('in' walks the prototype chain, so array methods, toString... never trigger a false positive).
+				// toJSON is asked by JSON.stringify to every object: a plain one has none, and that is not an error
 				if( !( prop in target ) ) {
-					console.error( `state error, unable to find ${_child_path(path,prop,target)}` );
+					if( prop !== "toJSON" ) {
+						console.error( `state error, unable to find ${_child_path(path,prop,target)}` );
+					}
+
 					return undefined;
 				}
 
@@ -237,7 +241,7 @@ export class StateManager<T extends State> extends EventSource<StateEvents> {
  * 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"
+ * state.items.push( 4 ); // "items[3] = 4"
  */
 
 export function makeState<T extends Record<keyof T, StateData>>( initialState: T ): StateProxy<T> {

package/src/core/core_tools.ts

@@ -264,7 +264,7 @@ export class Rect implements IRect {
 
     moveTo( x: number, y: number ) {
         this.left = x;
-        this.top = x;
+        this.top = y;
 
         return this;
     }

package/src/x4.d.ts

@@ -25,6 +25,7 @@ export * from "./core/core_i18n";
 export * from "./core/core_pdf";
 export * from "./core/core_react";
 export * from "./core/core_router";
+export * from "./core/core_shortcuts";
 export * from "./core/core_state";
 export * from "./core/core_styles";
 export * from "./core/core_svg";

package/src/x4.ts

@@ -26,6 +26,7 @@ export * from "./core/core_i18n"
 export * from "./core/core_pdf"
 export * from "./core/core_react"
 export * from "./core/core_router"
+export * from "./core/core_shortcuts"
 export * from "./core/core_state"
 export * from "./core/core_styles"
 export * from "./core/core_svg"