x4js 2.3.13 → 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)
 ```
 
@@ -130,7 +131,7 @@ interface ComponentProps {
   ns?: string                                        // SVG/MathML namespace
   cls?: string                                       // extra CSS classes
   id?: string
-  style?: Partial<CSSStyleDeclaration>
+  style?: StyleProps                                 // numbers get "px" except unitless
   attrs?: Record<string, string | number | boolean>
   content?: ComponentContent
   dom_events?: GlobalDOMEvents
@@ -188,7 +189,7 @@ getInternalData<T>(name: string|symbol): T
 ### Styles
 
 ```ts
-setStyle(style: Partial<CSSStyleDeclaration>): this  // numbers auto-suffixed "px" except unitless
+setStyle(style: StyleProps): this  // numbers auto-suffixed "px" except unitless
 setStyleValue<K>(name: K, value): this
 getStyleValue<K>(name: K): CSSStyleDeclaration[K]
 setWidth(w: number|string): void
@@ -633,7 +634,20 @@ class AutoComplete extends TextEdit {
 ### `ColorInput`
 
 ```ts
-class ColorInput extends HBox {}           // queryInterface("form-element")
+interface ColorInputProps extends BoxProps {
+  color: Color | string                    // null: no color shown
+  name?: string
+  format?: "rgb" | "hex"                   // text of the field, "rgb" by default
+  picker?: boolean                         // a click on the swatch opens a ColorPicker
+  swatches?: (Color|string)[] | (() => (Color|string)[])   // a function is called each time the picker opens
+  nullable?: boolean                       // "no color" can be chosen
+  change?: EventCallback<EvColorChange>    // user changes only, not setColor
+}
+class ColorInput extends HBox {            // queryInterface("form-element"): "#rrggbb" or null
+  getColor(): Color; getValue(): string
+  setColor(color: Color | string): void; setSwatches(swatches): void
+}
+interface EvColorChange extends EvChange { color: Color; value: string }  // "#rrggbb" or "#rrggbbaa"; both null for "no color"
 ```
 
 ### `FileDrop` / `FileDialog`
@@ -796,6 +810,9 @@ class PropertyGrid extends VBox {
   setItems(groups: PropertyGroup[]): void
   setPropValue(name: string, value): void
 }
+// PropertyValue.type: 'boolean' | 'number' | 'string' | 'password' | 'options' | 'color' | 'label' | 'button'
+// 'color': the editor is a ColorInput (hex, with picker); swatches?: string[] | (() => string[]), nullable?: boolean,
+//          callback(name, value) receives "#rrggbb", or null for "no color"
 ```
 
 ---
@@ -978,7 +995,9 @@ class Video extends Box {
   set stream(stream: MediaStream)
 }
 class Calendar extends VBox { getDate(): Date; setDate(date: Date): void }
-class ColorPicker extends VBox             // queryInterface("form-element")
+class ColorPicker extends VBox {           // props: color, swatches?, nullable?; "change": EvColorChange, also fired once when built
+  getColor(): Color; setColor(color: Color | string): void; setSwatches(swatches): void
+}
 class Panel extends VBox { setTitle(title: string): void }
 class Breadcrumbs extends HBox { setItems(elements): void }
 class Keyboard extends HBox                // virtual keyboard
@@ -1259,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
@@ -1469,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.13",
+  "version": "2.3.15",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",

package/src/components/colorinput/colorinput.module.scss

@@ -17,7 +17,8 @@
 :root {
 	--colorinput-btn-background: inherit;
 	--colorinput-btn-color: var( --text-secondary );
-	--colorinput-btn-color-hover: var( --text-primary );	
+	--colorinput-btn-color-hover: var( --text-primary );
+	--colorinput-popup-background: var( --background-primary );
 }
 
 .x4colorinput {
@@ -33,6 +34,27 @@
 		margin: 4px;
 		width: 1rem;
 		height: 1rem;
+
+		// props.picker: a click opens the color picker. It is a button:
+		// wide enough to be aimed at.
+		&.picker {
+			flex-shrink: 0;
+			width: 2.4rem;
+			height: 1.4rem;
+			border: 1px solid var( --border );
+			border-radius: 3px;
+			cursor: pointer;
+
+			&:hover {
+				border-color: var( --border-focus );
+			}
+		}
+
+		// props.nullable, no color: crossed out
+		&.none {
+			border: 1px solid var( --border );
+			background: linear-gradient( to top right, transparent 45%, #d04040 45%, #d04040 55%, transparent 55% );
+		}
 	}
 
 	input {
@@ -42,14 +64,19 @@
 		flex-grow: 1;
 	}
 
+	// the eye dropper: as high as the field, and wide enough to be aimed at
 	.x4button {
+		flex-shrink: 0;
+		align-self: stretch;
 		margin: 0;
-		padding: 0;
+		padding: 0 6px;
 		outline: none;
 		background-color: var( --combobox-btn-background );
 		color: var( --colorinput-btn-color );
 
 		#icon {
+			width: 1.3em;
+			height: 1.3em;
 			color: var( --colorinput-btn-color );
 		}
 
@@ -62,4 +89,11 @@
 			//color: var( --color-10 );
 		}
 	}
+}
+
+// the color picker opened from the swatch (props.picker)
+.x4colorinput-popup {
+	background-color: var( --colorinput-popup-background );
+	border: 1px solid var( --border );
+	box-shadow: 0 4px 12px rgba( 0, 0, 0, 0.3 );
 }

package/src/components/colorinput/colorinput.ts

@@ -1,40 +1,70 @@
-/** 
+/**
  *  ___  ___ __
  *  \  \/  /  / _
  *   \    /  /_| |_
- *   /    \____   _|  
+ *   /    \____   _|
  *  /__/\__\   |_|
- * 
+ *
  * @file colorinput.ts
- * @author Etienne Cochard 
- * 
+ * @author Etienne Cochard
+ *
  * @copyright (c) 2026 R-libre ingenierie
  *
- * Use of this source code is governed by an MIT-style license 
+ * 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 { Component } from '../../core/component';
-import { isFeatureAvailable, class_ns } from '../../core/core_tools';
+import { Component, ComponentEvents } from '../../core/component';
+import { EventCallback } from '../../core/core_events';
+import { isFeatureAvailable, class_ns, isFunction, IComponentInterface, IFormElement } from '../../core/core_tools';
 import { Color } from '../../core/core_colors';
 
 import { BoxProps, HBox } from '../boxes/boxes';
 import { Input } from '../input/input';
 import { Button } from '../button/button';
+import { Popup } from '../popup/popup';
+import { ColorPicker, EvColorChange } from '../colorpicker/colorpicker';
 
 
 import "./colorinput.module.scss"
 import icon from "./crosshairs-simple-sharp-light.svg"
 
-//TODO: add swatches
 //TODO: better keyboard handling (selection after cursor)
 
+type Swatches = ( Color | string )[];
+
 /**
- * 
+ *
  */
 
-interface ColorInputProps extends BoxProps {
+export interface ColorInputProps extends BoxProps {
+	/** The color at start. null: no color is shown. */
 	color: Color | string;
+
+	/** Name of the field: with it, a Form reads and writes the color (as "#rrggbb"). */
+	name?: string;
+
+	/** How the field writes the color. "rgb" by default: rgb(r,g,b). "hex": #rrggbb. */
+	format?: "rgb" | "hex";
+
+	/** A click on the swatch opens a color picker. */
+	picker?: boolean;
+
+	/**
+	 * Colors offered in the picker. A function is called each time the
+	 * picker opens: the list may change with time.
+	 */
+	swatches?: Swatches | ( ( ) => Swatches );
+
+	/** The field may have no color: emptied, or "no color" picked. */
+	nullable?: boolean;
+
+	/** The user changed the color (not fired by setColor). */
+	change?: EventCallback<EvColorChange>;
+}
+
+interface ColorInputEvents extends ComponentEvents {
+	change: EvColorChange;
 }
 
 /**
@@ -43,56 +73,199 @@ interface ColorInputProps extends BoxProps {
  * --colorinput-btn-background
  * --colorinput-btn-color
  * --colorinput-btn-color-hover
+ * --colorinput-popup-background
  * ```
  */
 
 @class_ns( "x4" )
-export class ColorInput extends HBox<ColorInputProps> {
+export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 	static "$cls-ns" = "x4";
 
+	private _color: Color;				// null: no color
+	private _swatch: Component;
+	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 );
 
-		let swatch: Component;
-		let edit: Input;
+		this.mapPropEvents( props, "change" );
+		this._swatches = props.swatches;
+
+		if( props.name ) {
+			this.setAttribute( "name", props.name );
+		}
 
 		this.setContent( [
-			swatch = new Component( { cls: "swatch" } ),
-			edit = new Input( { type: "text", value: "", spellcheck: false } ),
+			this._swatch = new Component( { cls: "swatch" } ),
+			this._edit = new Input( { type: "text", value: "", spellcheck: false } ),
 
 			isFeatureAvailable("eyedropper") ? new Button( { icon: icon, click: ( ) => {
 				const eyeDropper = new (window as any).EyeDropper();
 				eyeDropper.open( ).then( ( result: any ) => {
-					color = new Color( result.sRGBHex );
-					updateColor( color );
+					this._changed( new Color( result.sRGBHex ) );
 				}).catch( (_: any ) => {
 					/* silence */
 				});
 			} } ) : null
 		])
 
-		edit.addDOMEvent( "input", ( ) => {
-			const txt = edit.getValue( );
+		this._edit.addDOMEvent( "input", ( ) => {
+			const txt = this._edit.getValue( );
+
+			if( this.props.nullable && txt.trim( )=="" ) {
+				this._changed( null, false );
+				return;
+			}
+
 			const clr = new Color( txt );
 			if( !clr.isInvalid() ) {
-				color = clr;
-				updateColor( color );
+				this._changed( clr );
 			}
 		});
 
-		const updateColor = ( clr: Color ) => {
-			swatch.setStyleValue( "backgroundColor", clr.toRgbString(false) );
-			edit.setValue( clr.toRgbString(false) );
+		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, 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", ev => { wasOpen = this._closedAt >= ev.timeStamp; } );
+			this._swatch.addDOMEvent( "click", ( ) => {
+				if( !wasOpen ) {
+					this._openPicker( );
+				}
+			} );
+		}
+
+		this._show( this._parse( props.color ) );
+	}
+
+	private _parse( color: Color | string ): Color {
+		if( color instanceof Color ) {
+			return color;
 		}
 
-		let color: Color;
-		if( props.color instanceof Color ) {
-			color = props.color;
+		// Nothing to show (a color that is not known, or several ones). Whether
+		// the user may choose "no color" is another matter: props.nullable.
+		if( color===null || color===undefined || color==="" ) {
+			return null;
+		}
+
+		return new Color( color );
+	}
+
+	private _format( color: Color ): string {
+		return this.props.format=="hex" ? color.toHexString( ) : color.toRgbString( false );
+	}
+
+	/**
+	 * show a color: swatch and text
+	 * @param text false while the user empties the field: the text is left alone
+	 */
+
+	private _show( color: Color, text = true ) {
+		this._color = color;
+
+		this._swatch.setClass( "none", !color );
+		this._swatch.setStyleValue( "backgroundColor", color ? color.toRgbString(false) : null );
+
+		if( text ) {
+			this._edit.setValue( color ? this._format( color ) : "" );
 		}
-		else {
-			color = new Color( props.color );
+	}
+
+	/**
+	 * the user changed the color
+	 */
+
+	private _changed( color: Color, text = true ) {
+		this._show( color, text );
+		this.fire( "change", { color, value: color ? color.toHexString( ) : null } );
+	}
+
+	/**
+	 * The color picker, with the swatches, under the field. It closes on
+	 * a click outside of it.
+	 */
+
+	private _openPicker( ) {
+		const swatches = isFunction( this._swatches ) ? this._swatches( ) : this._swatches;
+
+		// the picker works on its own color: it changes it in place
+		const picker = new ColorPicker( {
+			color: this._color ? new Color( this._color.toHexString( ) ) : new Color( 255, 255, 255 ),
+			swatches,
+			nullable: this.props.nullable,
+		} );
+
+		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 => {
+			this._changed( ev.color ? new Color( ev.value ) : null );
+
+			if( !ev.color ) {
+				popup.close( );
+			}
+		} );
+
+		popup.displayNear( this.getBoundingRect( ), "top left", "bottom left", { x: 0, y: 6 } );
+	}
+
+	/**
+	 * The current color, null when there is none.
+	 */
+
+	getColor( ): Color {
+		return this._color;
+	}
+
+	/**
+	 * The current color as "#rrggbb" ("#rrggbbaa" when it is not opaque),
+	 * null when there is none.
+	 */
+
+	getValue( ): string {
+		return this._color ? this._color.toHexString( ) : null;
+	}
+
+	/**
+	 * Shows another color, or none (null). Does not fire `change`.
+	 */
+
+	setColor( color: Color | string ) {
+		this._show( this._parse( color ) );
+	}
+
+	/**
+	 * Changes the colors offered in the picker (see props.swatches).
+	 */
+
+	setSwatches( swatches: Swatches | ( ( ) => Swatches ) ) {
+		this._swatches = swatches;
+	}
+
+	/**
+	 *
+	 */
+
+	override queryInterface<T extends IComponentInterface>( name: string ): T {
+		if( name=="form-element" ) {
+			const i: IFormElement = {
+				getRawValue: ( ): any => { return this.getValue( ); },
+				setRawValue: ( v: any ) => { this.setColor( v ); },
+				isValid: ( ) => { return true; }
+			};
+
+			return i as unknown as T;
 		}
 
-		updateColor( color );
+		return super.queryInterface( name );
 	}
-}
+}

package/src/components/colorpicker/colorpicker.module.scss

@@ -130,4 +130,27 @@
 			}
 		}
 	}
+
+	// the colors offered under the sliders (props.swatches)
+	.swatches {
+		flex-wrap: wrap;
+		gap: 4px;
+
+		.item {
+			width: 18px;
+			height: 18px;
+			border: 1px solid var( --border );
+			border-radius: 3px;
+			cursor: pointer;
+
+			&:hover {
+				border-color: var( --border-focus );
+			}
+
+			// no color: crossed out
+			&.none {
+				background: linear-gradient( to top right, transparent 45%, #d04040 45%, #d04040 55%, transparent 55% );
+			}
+		}
+	}
 }