x4js 2.3.14 → 2.3.16

package/src/core/component.ts

@@ -21,6 +21,7 @@ import { CoreEvent, EventMap } from './core_events';
 import { addEvent, DOMEventHandler, GlobalDOMEvents, COMPONENT } from './core_dom';
 import { Application, EvMessage } from './core_application';
 import { makeState } from './core_state.js';
+import { Shortcuts, ShortcutCallback, ShortcutOptions } from './core_shortcuts';
 
 type ComponentAttributes = Record<string,string|number|boolean>;
 type CreateComponentCallBack =  ( attrs: Record<string,string> ) => ComponentContent;
@@ -169,6 +170,7 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 
 	#store: Map<string|symbol,any>;
 	#pstate: any;
+	#shortcuts: Shortcuts;
 
 	constructor(props: P) {
 		super( );
@@ -1169,6 +1171,40 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 		return null;
 	}
 
+	// :: SHORTCUTS ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+	/**
+	 * Adds a keyboard shortcut to the component. It works while the focus
+	 * is in the component, and while the focus is nowhere if this component
+	 * is the last one with shortcuts that had it: of two views that are shown
+	 * together, the one the user works in answers.
+	 *
+	 * A key that a child has used (it prevented its default, or stopped its
+	 * propagation) is not a shortcut. Nor is a key typed in a field, unless
+	 * `editable` is set.
+	 *
+	 * @param keys - "Mod+C", "Shift+Mod+Z", "Delete"... or several of them. Mod is Ctrl, or Cmd on a Mac.
+	 * @see Application.addShortcut for the shortcuts of the whole application
+	 *
+	 * @example
+	 * this.addShortcut( "Mod+C", ( ) => this.copy( ) );
+	 * this.addShortcut( ["Mod+Y", "Shift+Mod+Z"], ( ) => this.redo( ) );
+	 */
+
+	addShortcut( keys: string | string[], callback: ShortcutCallback, options?: ShortcutOptions ): this {
+		if( !this.#shortcuts ) {
+			const shortcuts = this.#shortcuts = new Shortcuts( );
+
+			// straight on the element, not with addDOMEvent: the handlers of the
+			// children are called exactly as before
+			this.dom.addEventListener( "keydown", ( ev ) => shortcuts.handle( ev as KeyboardEvent ) );
+			this.dom.addEventListener( "focusin", ( ) => Application.instance( ).setActiveShortcuts( this, shortcuts ) );
+		}
+
+		this.#shortcuts.add( keys, callback, options );
+		return this;
+	}
+
 	// :: PERSISTENCE ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 	protected loadPState( name: string, defaults: Record<string, any> ): any {
@@ -1194,9 +1230,10 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 
 		const state = makeState( raw );
 
+		// the state is what is saved, not raw: makeState works on a copy of it
 		state.on( "change", ( ) => {
 			this.setTimeout( key, 500, ( ) => {
-				Application.instance().setStorage( key, JSON.stringify( raw ) );
+				Application.instance().setStorage( key, JSON.stringify( state ) );
 		} );
 		});
 

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/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"