x4js 2.3.9 → 2.3.11

package/aicontext.md

@@ -26,7 +26,7 @@ import { ... } from 'x4js'   // src/x4.ts
 CoreElement<E>                 named timers + event surface (no DOM)
   ├── Component<P,E>           base DOM component
   │     ├── Box<P,E>
-  │     │     ├── HBox / VBox
+  │     │     ├── HBox / VBox → HSplitBox / VSplitBox
   │     │     ├── StackBox → AssistBox
   │     │     ├── GridBox / MasonryBox
   │     │     ├── Form
@@ -35,10 +35,11 @@ CoreElement<E>                 named timers + event surface (no DOM)
   │     │     ├── BtnGroup, Tabs, Video, Saturation
   │     ├── Button, Input, Icon, Label, SimpleText, Checkbox, Radio, Link
   │     ├── Listbox, Gridview, Treeview, Select, Combobox, Slider, Gauge
-  │     ├── Progress, TickLine, Canvas, Image, SvgComponent, Spreadsheet, MonacoEditor
+  │     ├── Progress, TickLine, Canvas, Image, Spreadsheet, MonacoEditor
+  │     ├── SvgComponent → Chart
   │     ├── CSizer → HSizer / VSizer
   │     ├── FileDialog, ScrollView, Viewport, Flex, Space
-  │     ├── HBox-based: ColorInput, Rating, Switch, Keyboard, TextEdit, Breadcrumbs
+  │     ├── HBox-based: ColorInput, Rating, Switch, Keyboard, TextEdit → AutoComplete, Breadcrumbs
   │     └── VBox-based: Calendar, ColorPicker, FileDrop, Panel, PropertyGrid, TextArea
   └── Application<E>           singleton, no DOM of its own
 
@@ -608,6 +609,26 @@ class Combobox extends Component {
 }
 ```
 
+### `AutoComplete` — text field with on-demand suggestions
+
+```ts
+interface AutoCompleteProps extends TextEditProps {   // label, labelWidth, required, placeholder, value...
+  search: (ev: EvSearch) => void            // required; ev.text, ev.setItems(items) — may be called async
+  change?                                   // EvAutoCompleteChange { value, item /* null = free text */ }
+  strict?: boolean                          // only a picked item (or empty) is accepted; default false
+  itemValue?: "text" | "id"                 // what goes into the field when an item is picked; default "text"
+  delay?: number                            // ms before search, default 250
+  minChars?: number                         // default 1
+  renderer?: (item: ListItem) => Component
+}
+class AutoComplete extends TextEdit {
+  getSelection(): ListboxID                 // id of the picked item, undefined for a free text
+  setSelection(item: ListItem): void;  showDropDown(): void
+}
+// Use Combobox for a fixed, known list; AutoComplete when suggestions come from a search (server).
+// In a Form the value is the field content (text or id, per itemValue).
+```
+
 ### `ColorInput`
 
 ```ts
@@ -710,12 +731,29 @@ interface SpreadsheetProps extends ComponentProps {
   columns: SpreadsheetColumn[]              // required
   footer?: boolean
   rowClassifier?: RowClassifier
+  enterMove?: "down" | "right" | "none"     // selection move after Enter in a cell editor (default "down")
   click?, dblClick?, contextMenu?, selectionChange?
+  cellChange?                               // EvCellChange, fired before an edited value is written to the store
+}
+interface SpreadsheetColumn {               // GridColumn +
+  editable?: boolean | ((row, col) => boolean)       // inline edition (off by default), col = column index
+  editor?: (row, col, value) => Component            // custom editor, must implement queryInterface("form-element")
 }
+interface EvCellChange { row; col /* index */; colId /* store key */; value /* writable */; oldValue }
 class Spreadsheet extends Component {
   getSelection(): /* cell */; navigate(sens: kbNav): boolean; lock(lock): void
+  editCell(row, col, clear = false): boolean         // cell must be visible
+  stopEdit(commit = true): void;  isEditing(): boolean
 }
 
+// Inline edition: F2 / Enter / double-click / typing starts, Enter / Tab / click elsewhere validates, Escape cancels,
+// Delete clears, editable checkboxes toggle on click or Space. Default editor is an Input matching the column type.
+// cellChange: ev.preventDefault() refuses the value, ev.value can be replaced.
+// Select / Combobox in a cell (the store holds the id, use `formatter` to display the text):
+//   { id: 2, title: "Status", width: 120, editable: true,
+//     formatter: ( id ) => states.find( x => x.id===id )?.text,
+//     editor: ( row, col, value ) => new Select( { items: states, value } ) }
+
 // Store: in-memory cell store (extends CoreElement)
 class Store extends CoreElement {
   setData(row, col, data): void;  getData(row, col): any;  hasData(row, col?): boolean
@@ -724,6 +762,28 @@ class Store extends CoreElement {
 }
 ```
 
+### `Chart` — minimal svg chart (line, area, bar, pie, donut)
+
+```ts
+interface ChartProps extends SvgProps {
+  type?: "line" | "area" | "bar" | "pie" | "donut"   // default "line"
+  series: ChartSerie[]                      // required; pie & donut use the first serie
+  labels?: string[]                         // default: 1, 2, 3...
+  xaxis?: ChartAxis;  yaxis?: ChartAxis     // { name?, ticks?, min?, max?, step? }, all computed by default
+  legend?: boolean                          // default: shown when 2+ named series
+  stacked?: boolean
+  formatter?: (value: number) => string     // default: chartFormatUnit (1.5k, 2M...)
+  click?                                    // EvChartClick { serie, index, value }
+}
+interface ChartSerie { name?; values: number[] /* undefined = hole */; color?; fill?; dots? }
+class Chart extends SvgComponent {
+  setType(type): void;  setSeries(series, labels?): void;  setLabels(labels): void
+  setTicks(sens: "x" | "y", ticks: ChartTick[]): void
+}
+// Colors: CSS variables --chart-color-1..8 (or serie.color). Size it with width/height/flex like any component.
+// Minimal by design: no dual axis, mixed types, time axis, zoom or animation — use a dedicated library for those.
+```
+
 ### `PropertyGrid`
 
 ```ts
@@ -894,6 +954,13 @@ class Form extends Box {
 ## Sizers / viewport / misc
 
 ```ts
+// PREFERRED for resizable panels: HSplitBox / VSplitBox (sizers are inserted automatically between panels).
+// The panel with `flex` takes the remaining space, its neighbour is the one resized.
+class HSplitBox extends HBox               // panels side by side, resizable width:  { content: Component[] }
+class VSplitBox extends VBox               // panels stacked, resizable height:      { content: Component[] }
+// new HSplitBox( { content: [ new Treeview( { width: 250 } ), new Panel( { flex: 1 } ) ] } )
+
+// Low level: only place sizers by hand when a SplitBox does not fit (popup edges, header cells...).
 class CSizer extends Component             // base splitter
 class HSizer extends CSizer                // horizontal splitter
 class VSizer extends CSizer                // vertical splitter

package/aiguide.md

@@ -132,6 +132,23 @@ super();
 
 when the component expects props.
 
+When writing a custom component, pass the whole props object: do not remove your own values from it before calling `super`. The base class keeps what it receives in `this.props`, so they stay readable later.
+
+```ts
+// avoid: search and strict are lost for this.props
+const { search, strict, ...base } = props;
+super(base);
+
+// prefer: override only what must not reach the parent
+super({ ...props, type: "text" });
+```
+
+Connect the event callbacks given in props with `mapPropEvents`, not with hand-written `if (props.x) this.on(...)`:
+
+```ts
+this.mapPropEvents(props, "change", "search");
+```
+
 For derived application components, prefer building the component's main content explicitly after `super(props)`.
 
 Ordinary nested x4 components may naturally use their `content` property where convenient.
@@ -192,6 +209,10 @@ Component objects
 Real DOM
 ```
 
+`addDOMEvent` belongs to custom components (a canvas-based widget, for example).
+
+On standard components, use their props and events.
+
 ---
 
 ## 6. Objects vs JSX
@@ -327,6 +348,12 @@ export const deviceModel = new DeviceModel();
 
 A model may encapsulate server access directly.
 
+Views should never call `fetch`.
+
+All server access goes through model classes deriving from one base class that owns the single `fetch` call (timeout, network failure, HTTP status, expired session, fetch mask).
+
+Create one model per functional domain. It normally corresponds to one URL root.
+
 Keep responsibilities simple:
 
 ```text id="t39sbp"
@@ -467,6 +494,18 @@ Do not introduce a JavaScript theme abstraction simply to mirror CSS variables.
 
 Presentation belongs in CSS when CSS already solves the problem.
 
+CSS styles a component; it never removes behaviour.
+
+Do not hide a control a component creates: configure the component through its props (for example `closable: false`).
+
+If the props cannot express it, say so instead of working around it.
+
+To retheme an application, redefine the primary colour scale (`--color-primary-a5` … `--color-primary-a90`) once per theme.
+
+Do not recolour components one by one, and do not override the variables derived from the scale.
+
+A dark theme gets its own scale.
+
 ---
 
 ## 19. Browser and TypeScript capabilities
@@ -578,6 +617,27 @@ The goal is to build the application with the smallest set of mechanisms that ke
 
 ---
 
+## 23. Translations
+
+x4 starts in French.
+
+Application texts are declared with `addTranslation` for each language.
+
+Select the language before any component is built, since a component reads its texts at construction.
+
+Call `selectLanguage` after `addTranslation`:
+
+```ts
+addTranslation("fr", { /* ... */ });
+addTranslation("en", { /* ... */ });
+
+selectLanguage("en");
+
+// only now build the application components
+```
+
+---
+
 ## Final rule
 
 When generating x4 code:

package/package.json

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

package/src/components/autocomplete/autocomplete.module.scss

@@ -0,0 +1,28 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file autocomplete.module.scss
+ * @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 field itself is a textedit
+
+.x4dropdownlist.autocomplete {
+	.x4item {
+		gap: 8px;
+
+		.id {
+			font-weight: 500;
+			min-width: 4em;
+		}
+	}
+}

package/src/components/autocomplete/autocomplete.ts

@@ -0,0 +1,361 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file autocomplete.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 { Component, ComponentEvent, ComponentEvents, EvChange } from '../../core/component';
+import { EventCallback } from '../../core/core_events';
+import { class_ns, kbNav } from '../../core/core_tools';
+
+import { HBox } from '../boxes/boxes';
+import { DropdownList } from '../combobox/combobox';
+import { TextInputProps } from '../input/input';
+import { SimpleText } from '../label/label';
+import { ListboxID, ListItem } from '../listbox/listbox';
+import { TextEdit, TextEditBase } from '../textedit/textedit';
+
+import "./autocomplete.module.scss"
+
+/**
+ * fired when suggestions are needed for a text
+ * setItems can be called later (async), late answers are ignored
+ */
+
+export interface EvSearch extends ComponentEvent {
+	text: string;
+	setItems: ( items: ListItem[] ) => void;
+}
+
+/**
+ * fired when the value is validated
+ */
+
+export interface EvAutoCompleteChange extends EvChange {
+	item: ListItem;		// picked item, null for a free text
+}
+
+interface AutoCompleteEvents extends ComponentEvents {
+	search: EvSearch;
+	change: EvAutoCompleteChange;
+}
+
+export interface AutoCompleteProps extends Omit<TextInputProps,"type"|"change">, TextEditBase {
+	search: EventCallback<EvSearch>;
+	change?: EventCallback<EvAutoCompleteChange>;
+
+	/** only a picked item (or nothing) is accepted, default false: free text is kept */
+	strict?: boolean;
+
+	/** what is written in the field when an item is picked (default "text") */
+	itemValue?: "text" | "id";
+
+	/** delay between the last key and the search, in ms (default 250) */
+	delay?: number;
+
+	/** number of chars needed to start a search (default 1) */
+	minChars?: number;
+
+	/** custom renderer for the suggestions */
+	renderer?: ( item: ListItem ) => Component;
+}
+
+// suggestion as: id + text
+const render_id_item = ( item: ListItem ) => {
+	return new HBox( {
+		cls: item.cls,
+		content: [
+			new SimpleText( { cls: "id", text: item.id+"" } ),
+			new SimpleText( { cls: "text", text: item.text } ),
+		]
+	});
+}
+
+/**
+ * Text field with suggestions asked on demand (search event).
+ *
+ * @example
+ * new AutoComplete( {
+ *   label: "Customer",
+ *   strict: true,
+ *   search: async ( ev ) => {
+ *     const rows = await api.searchCustomers( ev.text );
+ *     ev.setItems( rows.map( r => ( { id: r.id, text: r.name } ) ) );
+ *   },
+ *   change: ( ev ) => console.log( ev.value, ev.item ),
+ * })
+ */
+
+@class_ns( "x4" )
+export class AutoComplete extends TextEdit<AutoCompleteEvents> {
+
+	private _popup: DropdownList;
+
+	private _strict: boolean;
+	private _by_id: boolean;
+	private _delay: number;
+	private _min_chars: number;
+
+	private _text: string;		// last validated text
+	private _item: ListItem;	// last picked item (null: free text)
+	private _seq: number;		// search sequence, to ignore late answers
+	private _count: number;		// number of suggestions
+
+	constructor( props: AutoCompleteProps ) {
+		// the change of the input (each key) starts the search, our change event is fired on validation
+		super( { ...props, type: "text", change: ( ) => this._on_input( ) } );
+
+		this._strict = !!props.strict;
+		this._by_id = props.itemValue=="id";
+		this._delay = props.delay ?? 250;
+		this._min_chars = props.minChars ?? 1;
+
+		this._text = this.getInput( ).getValue( );
+		this._item = null;
+		this._seq = 0;
+		this._count = 0;
+
+		this.mapPropEvents( props, 'change', 'search' );
+
+		this._popup = new DropdownList( {
+			cls: "autocomplete",
+			items: [],
+			renderer: props.renderer ?? ( this._by_id ? render_id_item : undefined )
+		} );
+
+		this._popup.on( "click", ( ev ) => {
+			const item = this._popup.getList( ).getItem( ev.context as ListboxID );
+			if( item ) {
+				this._pick( item );
+			}
+		});
+
+		this.getInput( ).addDOMEvent( "keydown", ( ev ) => this._on_key( ev ) );
+
+		this.addDOMEvent( "focusout", ( ev ) => this._on_focusout( ev ) );
+	}
+
+	/**
+	 *
+	 */
+
+	private _on_input( ) {
+		const text = this.getInput( ).getValue( );
+
+		// pending answers are obsolete
+		this._seq++;
+
+		if( text.length<this._min_chars ) {
+			this.clearTimeout( "search" );
+			this._popup.show( false );
+			return;
+		}
+
+		this.setTimeout( "search", this._delay, ( ) => this._search( text ) );
+	}
+
+	/**
+	 *
+	 */
+
+	private _search( text: string ) {
+		const seq = ++this._seq;
+
+		const setItems = ( items: ListItem[] ) => {
+			// a newer search was started (or the field was left)
+			if( seq!=this._seq ) {
+				return;
+			}
+
+			this._setItems( items ?? [] );
+		}
+
+		this.fire( "search", { text, setItems } );
+	}
+
+	private _setItems( items: ListItem[] ) {
+		const list = this._popup.getList( );
+		list.setItems( items );
+		this._count = items.length;
+
+		if( !items.length ) {
+			this._popup.show( false );
+			return;
+		}
+
+		this.showDropDown( );
+
+		// strict: Enter picks the first suggestion
+		if( this._strict ) {
+			list.navigate( kbNav.first );
+		}
+	}
+
+	/**
+	 *
+	 */
+
+	private _on_key( ev: KeyboardEvent ) {
+		const list = this._popup.getList( );
+		const open = this._popup.isOpen( );
+
+		switch( ev.key ) {
+			case "ArrowUp":
+			case "ArrowDown": {
+				if( open ) {
+					list.navigate( ev.key=="ArrowDown" ? kbNav.next : kbNav.prev );
+				}
+				else if( this._count ) {
+					this.showDropDown( );
+				}
+				else {
+					this.clearTimeout( "search" );
+					this._search( this.getInput( ).getValue( ) );
+				}
+
+				break;
+			}
+
+			case "Enter": {
+				const [sel] = open ? list.getSelection( ) : [];
+				const item = sel!==undefined ? list.getItem( sel ) : null;
+
+				if( !item ) {
+					// nothing to pick: the key is not for us
+					this._popup.show( false );
+					return;
+				}
+
+				this._pick( item );
+				break;
+			}
+
+			case "Escape": {
+				if( !open ) {
+					return;
+				}
+
+				this._popup.show( false );
+				break;
+			}
+
+			default: {
+				return;
+			}
+		}
+
+		ev.preventDefault( );
+		ev.stopPropagation( );
+	}
+
+	/**
+	 *
+	 */
+
+	private _on_focusout( ev: FocusEvent ) {
+		// focus is moving inside the control
+		const to = ev.relatedTarget as Node;
+		if( to && this.dom.contains( to ) ) {
+			return;
+		}
+
+		this.clearTimeout( "search" );
+		this._seq++;
+		this._popup.show( false );
+
+		const input = this.getInput( );
+		const text = input.getValue( );
+		if( text===this._text ) {
+			return;
+		}
+
+		// strict: back to the last validated value (but the field can be emptied)
+		if( this._strict && text!=="" ) {
+			input.setValue( this._text );
+			return;
+		}
+
+		this._commit( text, null );
+	}
+
+	/**
+	 * an item was choosen in the suggestions
+	 */
+
+	private _pick( item: ListItem ) {
+		const text = ( this._by_id ? item.id : item.text ) + "";
+
+		this.clearTimeout( "search" );
+		this._seq++;
+
+		this.getInput( ).setValue( text );
+		this._popup.show( false );
+
+		this._commit( text, item );
+	}
+
+	private _commit( text: string, item: ListItem ) {
+		const changed = text!==this._text || item?.id!==this._item?.id;
+
+		this._text = text;
+		this._item = item;
+
+		if( changed ) {
+			this.fire( "change", { value: text, item } );
+		}
+	}
+
+	/**
+	 *
+	 */
+
+	showDropDown( ) {
+		if( this.isDisabled() || this._popup.isOpen( ) ) {
+			return;
+		}
+
+		const rc = ( this.query( ":scope > #edit" ) ?? this ).getBoundingRect( );
+		this._popup.setStyleValue( "minWidth", rc.width+"px" );
+		this._popup.displayNear( rc, "top left", "bottom left", {x:0,y:6} );
+	}
+
+	/**
+	 * change the text of the field (no item is selected, no event)
+	 */
+
+	override setValue( value: string ) {
+		super.setValue( value );
+
+		this._text = this.getInput( ).getValue( );
+		this._item = null;
+	}
+
+	/**
+	 * select an item as if it was picked in the suggestions (no event)
+	 */
+
+	setSelection( item: ListItem ) {
+		super.setValue( ( this._by_id ? item.id : item.text ) + "" );
+
+		this._text = this.getInput( ).getValue( );
+		this._item = item;
+	}
+
+	/**
+	 * @returns the id of the picked item, undefined if the text does not come from the suggestions
+	 */
+
+	getSelection( ): ListboxID {
+		return this.getInput( ).getValue( )===this._text ? this._item?.id : undefined;
+	}
+}

package/src/components/boxes/boxes.ts

@@ -17,6 +17,7 @@
 import { asap, class_ns, isArray, isNumber } from '../../core/core_tools';
 import { Component, ComponentEvents, ComponentProps, EvSelectionChange } from "../../core/component"
 import { EventCallback } from '../../core/core_events';
+import { HSizer, VSizer } from '../sizers/sizer';
 
 import "./boxes.module.scss";
 
@@ -91,6 +92,71 @@ export class VBox<P extends BoxProps=BoxProps,E extends ComponentEvents=Componen
 }
 
 
+// :: SPLITBOX ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+export interface SplitBoxProps extends Omit<BoxProps,"content"> {
+	/** Panels to lay out, a sizer is inserted between each of them. */
+	content: Component[];
+}
+
+/**
+ * insert a sizer between each panel.
+ * the sizer resizes the panel that is not flex (the flex one takes the remaining space),
+ * when both are of the same kind, the previous panel is resized.
+ */
+
+function split_content( panels: Component[], horz: boolean ) {
+	const els = panels?.filter( x => !!x ) ?? [];
+	const res: Component[] = [];
+
+	els.forEach( ( p, i ) => {
+		if( i>0 ) {
+			const prev = els[i-1];
+			const next = prev.hasClass( "x4flex" ) && !p.hasClass( "x4flex" );
+			res.push( horz ? new HSizer( next ) : new VSizer( next ) );
+		}
+
+		res.push( p );
+	});
+
+	return res;
+}
+
+/**
+ * A horizontal box where panels are separated by sizers: panels are side by side
+ * (like in a {@link HBox}) and the user can change their width.
+ * The CSS class for this component is automatically generated as `x4hsplitbox`.
+ *
+ * @example
+ * new HSplitBox( {
+ *   content: [
+ *     new Treeview( { width: 250, ... } ),		// resized by the sizer
+ *     new Panel( { flex: 1, ... } ),			// takes the remaining space
+ *   ]
+ * })
+ */
+
+@class_ns( "x4" )
+export class HSplitBox<P extends SplitBoxProps=SplitBoxProps,E extends ComponentEvents=ComponentEvents> extends HBox<P,E> {
+	constructor( props: P ) {
+		super( { ...props, content: split_content( props.content, true ) } );
+	}
+}
+
+/**
+ * A vertical box where panels are separated by sizers: panels are stacked
+ * (like in a {@link VBox}) and the user can change their height.
+ * The CSS class for this component is automatically generated as `x4vsplitbox`.
+ */
+
+@class_ns( "x4" )
+export class VSplitBox<P extends SplitBoxProps=SplitBoxProps,E extends ComponentEvents=ComponentEvents> extends VBox<P,E> {
+	constructor( props: P ) {
+		super( { ...props, content: split_content( props.content, false ) } );
+	}
+}
+
+
 type ContentBuilder = ( ) => Component;
 
 

package/src/components/button/button.ts

@@ -14,12 +14,12 @@
  * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
  **/
 
-import { Menu, MenuElement, MenuProps } from 'x4js';
 import { Component, ComponentEvents, ComponentProps, EvClick } from "../../core/component"
 import { EventCallback } from '../../core/core_events';
 import { class_ns, isFunction, UnsafeHtml } from '../../core/core_tools';
 
 import { Icon } from "../icon/icon"
+import { Menu, MenuElement } from '../menu/menu';
 
 import "./button.module.scss";