x4js 2.3.14 → 2.3.15

package/aicontext.md

@@ -46,10 +46,11 @@ CoreElement<E>                 named timers + event surface (no DOM)
 
 EventSource<E>                 standalone event registry
   ├── DataStore<T>
-  └── Router
+  ├── Router
+  └── StateManager<T>
 
 CoreElement-based (non-DOM): DataProxy, DataView, Store
-Standalone: Rect, Timer, Color, DataModel, StateManager, Stylesheet, ComputedStyle,
+Standalone: Rect, Timer, Color, DataModel, Stylesheet, ComputedStyle,
             SvgBuilder, X4PDFBuilder, x4_react, CMover, UnsafeHtml (extends String)
 ```
 
@@ -1277,17 +1278,36 @@ initTooltips(): void                                   // initialize the global
 
 ---
 
-## State (`core_state`) — Experimental
+## State (`core_state`)
 
 ```ts
-class StateManager {
-  constructor(initialState)
-  getState(path: string, defaultValue?): any
-  setState(path: string, value, context?): void
+makeState<T>(initialState: T): StateProxy<T>     // the data itself + on / off / once / watch
+
+const state = makeState({ count: 0, user: { name: '' }, items: [1, 2, 3] })
+state.on('change', e => ...)                     // EvStateChange { path, value }
+state.watch('user', e => ...)                    // 'user', anything below it, or a parent replaced; returns { off() }
+state.count++                                    // path "count"
+state.user.name = 'x'                            // path "user.name"
+state.items.push(4)                              // path "items[3]"
+
+class StateManager<T> extends EventSource<StateEvents> {
+  constructor(initialState: T)
+  proxify(): StateProxy<T>
+  on(name, listener): { off(): void }
+  off(name, listener): void
+  once(name, listener): { off(): void }
+  watch(path: string, cb: (ev: EvStateChange) => void): { off(): void }
 }
-// NOTE: marked @Experimental in the sources.
+
+// Component (protected): a state kept in localStorage under "x4@persist:<name>",
+// saved 500 ms after a change
+loadPState(name: string, defaults: Record<string, any>): any
 ```
 
+- Plain objects and arrays are proxied when read; Date, Map, Set and class instances are not.
+- Setting a property to the value it already has fires nothing.
+- Reading a property that does not exist logs an error and returns `undefined`.
+
 ---
 
 ## Common patterns
@@ -1487,7 +1507,6 @@ Optional keys: `external`, `define`, `esbuild`, `dev` (`host`, `port`, `https`,
 - The default language is `fr`. Call `selectLanguage('en')` to switch to English.
 - `Gridview` is backed by a `DataStore`; `Spreadsheet` is backed by a `Store` (different, cell-based).
 - `DataRecordID` is currently typed `any`; `strictNullChecks` is intentionally off in the recommended `tsconfig.json`.
-- `StateManager` (`core_state`) is marked **Experimental** — verify before relying on it.
 - `MonacoEditor` requires `MonacoEditor.start()` (async) before use; register extra typings with `MonacoEditor.addTypelib(name, code)`.
 - `x4_react.create_element` is the JSX pragma; 
 - `unbubbleEvents` is the set of DOM events that do not bubble through the x4 component tree.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.3.14",
+  "version": "2.3.15",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",

package/src/components/colorinput/colorinput.ts

@@ -86,6 +86,7 @@ export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 	private _edit: Input;
 	private _swatches: Swatches | ( ( ) => Swatches );
 	private _popup: Popup;				// the color picker, once it was opened
+	private _closedAt = -1;				// when it closed for the last time (performance.now)
 
 	constructor( props: ColorInputProps ) {
 		super( props );
@@ -128,11 +129,12 @@ export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 		if( props.picker ) {
 			// A click on the swatch opens the picker, a second one closes it.
 			// The picker closes by itself as soon as the button goes down
-			// outside of it: whether it was open is to be known before that.
+			// outside of it, before the swatch hears of it: it was open if
+			// it closed since this very press began.
 			let wasOpen = false;
 
 			this._swatch.addClass( "picker" );
-			this._swatch.addDOMEvent( "pointerdown", ( ) => { wasOpen = !!this._popup?.isOpen( ); } );
+			this._swatch.addDOMEvent( "pointerdown", ev => { wasOpen = this._closedAt >= ev.timeStamp; } );
 			this._swatch.addDOMEvent( "click", ( ) => {
 				if( !wasOpen ) {
 					this._openPicker( );
@@ -202,6 +204,7 @@ export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 		} );
 
 		const popup = this._popup = new Popup( { cls: "x4colorinput-popup", autoClose: true, content: picker } );
+		popup.on( "closed", ( ) => { this._closedAt = performance.now( ); } );
 
 		// after the construction: the picker fires a first change when it is built
 		picker.on( "change", ev => {

package/src/components/popup/popup.ts

@@ -233,7 +233,7 @@ export class Popup<P extends PopupProps = PopupProps, E extends PopupEvents = Po
 			if( idx>=0 ) {
 				autoclose_list.splice( idx, 1 );
 				if( autoclose_list.length==0 ) {
-					document.removeEventListener( "pointerdown", this._dismiss );
+					document.removeEventListener( "pointerdown", this._dismiss, true );
 				}
 			}
 		}
@@ -263,7 +263,7 @@ export class Popup<P extends PopupProps = PopupProps, E extends PopupEvents = Po
 				
 		if( this.props.autoClose ) {
 			if( autoclose_list.length==0 ) {
-				document.addEventListener( "pointerdown", this._dismiss );
+				document.addEventListener( "pointerdown", this._dismiss, true );
 			}
 
 			autoclose_list.push( this );
@@ -322,6 +322,10 @@ export class Popup<P extends PopupProps = PopupProps, E extends PopupEvents = Po
 
 	/**
 	 * binded
+	 *
+	 * listened on the document while the event goes down (capture): a press
+	 * closes the popups even when what is pressed stops its propagation.
+	 * the event is left as it is, what is pressed handles it as usual.
 	 */
 
 	private _dismiss = ( e: UIEvent ) => {
@@ -330,9 +334,6 @@ export class Popup<P extends PopupProps = PopupProps, E extends PopupEvents = Po
 			return;
 		}
 
-		e.preventDefault( );
-		e.stopPropagation( );
-
 		this.dismiss( );
 	}
 	
@@ -368,7 +369,7 @@ export class Popup<P extends PopupProps = PopupProps, E extends PopupEvents = Po
 		const list = inc_group.reverse( );
 		autoclose_list = excl_group;
 		if( autoclose_list.length==0 ) {
-			document.removeEventListener( "pointerdown", this._dismiss );
+			document.removeEventListener( "pointerdown", this._dismiss, true );
 		}
 		
 		list.forEach( x => x.close() );

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: KeyboardEvent ) => shortcuts.handle( ev ) );
+			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"