x4js 2.3.26 → 2.3.27

package/aicontext.md

@@ -36,7 +36,7 @@ CoreElement<E>                 named timers + event surface (no DOM)
   │     │     ├── BtnGroup, Tabs, Video, Saturation
   │     ├── Button, Input, Icon, Label, SimpleText, Checkbox, Radio, Link, SimpleTextArea
   │     ├── Listbox, Gridview, Treeview, Select, Combobox, Slider, Gauge
-  │     ├── Progress, TickLine, Canvas, Image, Spreadsheet, MonacoEditor
+  │     ├── Progress, TickLine, Timeline, Canvas, Image, Spreadsheet, MonacoEditor
   │     ├── SvgComponent → Chart
   │     ├── CSizer → HSizer / VSizer
   │     ├── FileDialog, ScrollView, Viewport, DockingView, Flex, Space
@@ -227,12 +227,16 @@ queryAll(selector: string): Component[]
 firstChild<T>(): T;  lastChild<T>(): T
 nextElement<T>(): T; prevElement<T>(): T
 parentElement<T>(cls?: Constructor<T>): T
+closest<T>(selector: string): T             // this one or an ancestor whose element matches the css selector; null if none
+contains(other: Component | Node): boolean  // other (a node, or the element of a component) is the element of this one or inside it
 childCount(): number
 enumChildComponents(recursive: boolean): Component[]
 enumChildNodes(recursive: boolean): Node[]
 visitChildren(cb: (el: Component) => boolean): void
 static parentElement<T>(dom: Node, cls?: Constructor<T>): T   // starts at the parent of dom, not at dom:
                                                                // test componentFromDOM(dom) first for the component of dom itself
+static closest<T>(dom: Element, selector: string): T           // starts at dom itself: in a click handler,
+                                                               // Component.closest(ev.target as Element, '.item')
 ```
 
 ### Visibility / state / focus / geometry
@@ -614,6 +618,41 @@ class Rating extends HBox {
 }
 ```
 
+### `Timeline` — events on a line, each with its icon in a round mark
+
+```ts
+interface TimelineItem {
+  icon?: string                            // in the round mark
+  title: string | UnsafeHtml               // in bold
+  text?: string | UnsafeHtml               // the sentence under it, in grey
+  date?: Date                              // written relative to now, in the locale: "il y a 2 heures", "yesterday"; none: no time shown
+  done?: boolean                           // the mark in the accent; else a grey mark
+}
+interface TimelineProps extends ComponentProps {
+  items?: TimelineItem[]
+  vertical?: boolean                       // true by default; false: the events side by side
+  renderer?: (item: TimelineItem) => Component   // what is beside the mark (the mark and the line stay)
+  click?: EventCallback<EvClick>           // a click anywhere in an event: ev.context is its TimelineItem
+}
+interface TimelineEvents extends ComponentEvents { click: EvClick }
+class Timeline extends Component<TimelineProps, TimelineEvents> {
+  setItems(items: TimelineItem[]): void    // the relative times are written here, not updated after
+}
+// the line to the next mark: in the accent when the next event is done, dashed after an event not done
+// CSS vars: --timeline-done-color --timeline-done-icon-color --timeline-todo-color --timeline-todo-icon-color
+//           --timeline-title-color --timeline-text-color --timeline-time-color
+```
+
+```ts
+new Timeline({
+  items: [
+    { icon: branch, title: 'New branch', text: 'fix-notifications, from master', date: created, done: true },
+    { icon: review, title: 'Code review', text: 'Waiting for a reviewer' },
+  ],
+  click: ev => this.openStep(ev.context as TimelineItem),
+})
+```
+
 ---
 
 ## Input components
@@ -1453,6 +1492,7 @@ component.addShortcut(keys, callback, options?)         // a view: while the foc
 Application.instance().addShortcut(keys, callback, options?)   // the whole application, wherever the focus is
 
 shortcutText(keys: string): string                     // for a tooltip or a menu: "Ctrl+Z", "⌘Z" on a Mac
+isMac: boolean                                          // true on a Mac, an iPhone or an iPad: Mod is Cmd there
 
 class Shortcuts {                                       // the list itself; rarely used directly
   add(keys: string | string[], callback: (ev: KeyboardEvent) => void, options?: ShortcutOptions): void

package/package.json

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

package/src/components/autocomplete/autocomplete.ts

@@ -268,7 +268,7 @@ export class AutoComplete extends TextEdit<AutoCompleteEvents> {
 	private _on_focusout( ev: FocusEvent ) {
 		// focus is moving inside the control
 		const to = ev.relatedTarget as Node;
-		if( to && this.dom.contains( to ) ) {
+		if( to && this.contains( to ) ) {
 			return;
 		}
 

package/src/components/calendar/calendar.ts

@@ -358,7 +358,7 @@ export class PopupCalendar extends Popup {
 		let newfocus = <HTMLElement>e.target;
 
 		// child of this: ok
-		if (this.dom.contains(newfocus)) {
+		if (this.contains(newfocus)) {
 			return;
 		}
 

package/src/components/chart/chart.ts

@@ -264,7 +264,7 @@ export class Chart extends SvgComponent<ChartProps,ChartEvents> {
 
 		this.addDOMEvent( "click", ( e ) => {
 			const el = ( e.target as Element ).closest( "[data-index]" );
-			if( el && this.dom.contains( el ) ) {
+			if( el && this.contains( el ) ) {
 				const serie = parseInt( el.getAttribute( "data-serie" ) );
 				const index = parseInt( el.getAttribute( "data-index" ) );
 				this.fire( "click", { serie, index, value: this._series[serie]?.values[index] } );

package/src/components/components.ts

@@ -45,6 +45,7 @@ export * from "./tag/tag"
 export * from "./textarea/textarea"
 export * from "./textedit/textedit"
 export * from "./tickline/tickline"
+export * from "./timeline/timeline"
 export * from "./tooltips/tooltips"
 export * from "./treeview/treeview"
 export * from "./video/video"

package/src/components/dockingview/dockingview.ts

@@ -404,7 +404,7 @@ export class DockingView extends Component<DockingViewProps, DockingViewEvents>
 		this.fills.forEach( fill => fill( ) );
 		this.placeFloats( );
 
-		if( focused instanceof HTMLElement && this.dom.contains( focused ) ) {
+		if( focused instanceof HTMLElement && this.contains( focused ) ) {
 			focused.focus( );
 		}
 	}

package/src/components/listbox/listbox.ts

@@ -14,7 +14,7 @@
  * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
  **/
 
-import { Component, ComponentEvent, ComponentEvents, componentFromDOM, ComponentProps, EvChange, EvClick, EvContextMenu, EvDblClick, EvSelectionChange } from '../../core/component';
+import { Component, ComponentEvent, ComponentEvents, ComponentProps, EvChange, EvClick, EvContextMenu, EvDblClick, EvSelectionChange } from '../../core/component';
 import { EventCallback } from '../../core/core_events';
 import { kbNav, isArray, UnsafeHtml, asap } from '../../core/core_tools';
 
@@ -283,47 +283,38 @@ private _view: Viewport;
 	 */
 	
 	private _on_click( ev: MouseEvent ) {
-		let target = ev.target as HTMLElement;
-		let on_check = false;
+		const target = ev.target as Element;
 
-		while( target && target!=this.dom ) {
-			const c = componentFromDOM( target );
+		// avoid trapping child click
+		if( Component.closest( target, "input" ) ) {
+			return;
+		}
 
-			// avoid trapping child click
-			if( c && c.dom.tagName==='INPUT' ) {
+		// an item of this list, not of a list around it
+		const c = Component.closest( target, ".x4item" );
+		if( c && this.contains( c ) ) {
+			// the case changes alone; a double click on it is ignored
+			if( Component.closest( target, ".x4check" ) ) {
+				if( ev.type == 'click' ) {
+					this._toggleCheck( c );
+				}
 				return;
 			}
 
-			if( c && c.hasClass("x4check") ) {
-				on_check = true;
+			const id = c.getInternalData( "id" );
+			const fev: EvClick = { context:id };
+			if (ev.type == 'click') {
+				this.fire('click', fev );
+			}
+			else {
+				this.fire('dblClick', fev );
 			}
 
-			if( c && c.hasClass("x4item") ) {
-				// the case changes alone; a double click on it is ignored
-				if( on_check ) {
-					if( ev.type == 'click' ) {
-						this._toggleCheck( c );
-					}
-					return;
-				}
-
-				const id = c.getInternalData( "id" );
-				const fev: EvClick = { context:id };
-				if (ev.type == 'click') {
-					this.fire('click', fev );
-				}
-				else {
-					this.fire('dblClick', fev );
-				}
-
-				if (!fev.defaultPrevented) {
-					this._selectItem( id, c, ev.ctrlKey ? 'toggle' : 'single', ev.type == 'click' && this.props.reselect );
-				}
-				
-				return;
+			if (!fev.defaultPrevented) {
+				this._selectItem( id, c, ev.ctrlKey ? 'toggle' : 'single', ev.type == 'click' && this.props.reselect );
 			}
 
-			target = target.parentElement;
+			return;
 		}
 
 		if (ev.type == 'click') {
@@ -344,19 +335,14 @@ private _view: Viewport;
 
 		ev.preventDefault();		
 
-		let target = ev.target as HTMLElement;
-		while( target && target!=this.dom ) {
-			const c = componentFromDOM( target );
-			if( c && c.hasClass("x4item") ) {
-				const id = c.getInternalData( "id" );
-				
-				this._selectItem(id, c, 'single' );
-				this.fire('contextMenu', {uievent: ev, context: id } );
-			
-				return;
-			}
+		const c = Component.closest( ev.target as Element, ".x4item" );
+		if( c && this.contains( c ) ) {
+			const id = c.getInternalData( "id" );
 
-			target = target.parentElement;
+			this._selectItem(id, c, 'single' );
+			this.fire('contextMenu', {uievent: ev, context: id } );
+
+			return;
 		}
 
 		this.fire('contextMenu', { uievent:ev, context: null } );

package/src/components/monaco/monaco.ts

@@ -1,4 +1,3 @@
-import { class_ns } from '../../core/core_tools';
 import { Component, ComponentProps } from '../../core/component';
 
 import Monaco from './bin/monaco'; 
@@ -17,8 +16,8 @@ interface MonacoEditorProps extends ComponentProps {
 	options?: Monaco.editor.IEditorOptions & Monaco.editor.IGlobalEditorOptions;
 }
 
-@class_ns( "x4" )
 export class MonacoEditor extends Component<MonacoEditorProps> {
+	static classPrefix = "x4";
 
 	private static _initCount = 0;
 	private static _basePath: string = "monaco/";

package/src/components/popup/popup.ts

@@ -54,7 +54,7 @@ function getRoot( ) {
  */
 
 function dismissLast( e: UIEvent ) {
-	if( autoclose_list.some( x => x.dom.contains( e.target as Node ) ) ) {
+	if( autoclose_list.some( x => x.contains( e.target as Node ) ) ) {
 		return;
 	}
 
@@ -224,7 +224,7 @@ export class Popup<P extends PopupProps = PopupProps, E extends PopupEvents = Po
 		// modal: the focus goes back to the element that had it when it opened, unless the
 		// user put it elsewhere (read before the popup leaves the page and its focus with it)
 		const active = document.activeElement;
-		const giveBack = this._ismodal && this._prevFocus && ( !active || active===document.body || this.dom.contains( active ) );
+		const giveBack = this._ismodal && this._prevFocus && ( !active || active===document.body || this.contains( active ) );
 
 		this.__hide( );
 		this.__remove( );

package/src/components/rating/rating.ts

@@ -104,7 +104,7 @@ export class Rating extends HBox<RatingProps,RatingEventMap> {
 
 	// the star clicked: its svg, or the Icon itself
 	private _on_click( ev: MouseEvent ) {
-		const n = this.m_els.findIndex( c => c.dom.contains( ev.target as Node ) );
+		const n = this.m_els.findIndex( c => c.contains( ev.target as Node ) );
 		if( n>=0 ) {
 			// the star of the value, clicked again: none is lit
 			this.setValue( n+1===this.props.value ? 0 : n+1 );

package/src/components/timeline/timeline.module.scss

@@ -0,0 +1,147 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file timeline.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.
+ **/
+
+:root {
+	--timeline-done-color: var( --accent-background );
+	--timeline-done-icon-color: var( --accent-color );
+	--timeline-todo-color: var( --border );
+	--timeline-todo-icon-color: var( --text-ternary );
+	--timeline-title-color: var( --text-primary );
+	--timeline-text-color: var( --text-ternary );
+	--timeline-time-color: var( --text-primary );
+}
+
+// side by side: the marks on a line at the top, the content under each one
+
+.x4timeline {
+	display: flex;
+	flex-direction: row;
+
+	.item {
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 0;
+		min-width: 0;
+	}
+
+	.rail {
+		display: flex;
+		flex-direction: row;
+		align-items: center;
+	}
+
+	.mark {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		flex-shrink: 0;
+		width: 24px;
+		height: 24px;
+		border-radius: 50%;
+		background-color: var( --timeline-todo-color );
+
+		.x4icon {
+			height: 12px;
+			color: var( --timeline-todo-icon-color );
+			fill: var( --timeline-todo-icon-color );
+
+			&.empty {
+				display: none;
+			}
+		}
+	}
+
+	// the line to the next mark: only one side has a width
+	.line {
+		flex: 1;
+		border: 0 dashed var( --timeline-todo-color );
+		border-top-width: 2px;
+	}
+
+	.item.done > .rail {
+		.mark {
+			background-color: var( --timeline-done-color );
+
+			.x4icon {
+				color: var( --timeline-done-icon-color );
+				fill: var( --timeline-done-icon-color );
+			}
+		}
+
+		.line {
+			border-style: solid;
+		}
+	}
+
+	.item.next-done > .rail > .line {
+		border-color: var( --timeline-done-color );
+	}
+
+	.item:last-child > .rail > .line {
+		display: none;
+	}
+
+	.content {
+		padding: 8px 12px 0 0;
+	}
+
+	.title {
+		font-weight: bold;
+		color: var( --timeline-title-color );
+	}
+
+	.text {
+		color: var( --timeline-text-color );
+	}
+
+	.time {
+		margin-top: 4px;
+		font-size: 0.85em;
+		font-weight: 500;
+		color: var( --timeline-time-color );
+	}
+
+	// one under the other: the marks on a line on the left, the content beside each one
+
+	&.vertical {
+		flex-direction: column;
+
+		.item {
+			flex-direction: row;
+			flex: 0 0 auto;
+		}
+
+		.rail {
+			flex-direction: column;
+		}
+
+		.line {
+			border-top-width: 0;
+			border-left-width: 2px;
+		}
+
+		.content {
+			flex: 1;
+			min-width: 0;
+			padding: 0 0 1.5em 12px;
+		}
+
+		// the title on the middle of the mark
+		.title {
+			line-height: 24px;
+		}
+	}
+}

package/src/components/timeline/timeline.ts

@@ -0,0 +1,146 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file timeline.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, ComponentEvents, ComponentProps, EvClick } from '../../core/component';
+import { EventCallback } from '../../core/core_events';
+import { UnsafeHtml } from '../../core/core_tools';
+import { getCurrentLocale } from '../../core/core_i18n';
+import { Icon } from '../icon/icon';
+
+import "./timeline.module.scss";
+
+export interface TimelineItem {
+	icon?: string;					// in the round mark
+	title: string | UnsafeHtml;		// in bold
+	text?: string | UnsafeHtml;		// the sentence under it
+	date?: Date;					// written relative to now, in the locale: "2 hours ago"; none: no time shown
+	done?: boolean;					// the mark filled in the accent; else a grey mark
+}
+
+export interface TimelineEvents extends ComponentEvents {
+	click: EvClick;					// context: the TimelineItem clicked
+}
+
+export interface TimelineProps extends ComponentProps {
+	items?: TimelineItem[];
+	vertical?: boolean;				// true by default; false: the events side by side
+	renderer?: ( item: TimelineItem ) => Component;	// what is beside the mark
+	click?: EventCallback<EvClick>;
+}
+
+/**
+ * "2 hours ago", "yesterday", "in 3 days": the largest unit that gives at least 1
+ */
+
+function relativeTime( date: Date ): string {
+	const fmt = new Intl.RelativeTimeFormat( getCurrentLocale( ), { numeric: "auto" } );
+	const sec = ( date.getTime( ) - Date.now( ) ) / 1000;		// < 0: in the past
+	const abs = Math.abs( sec );
+
+	if( abs < 60 ) {
+		return fmt.format( Math.trunc( sec ), "second" );
+	}
+
+	if( abs < 3600 ) {
+		return fmt.format( Math.trunc( sec / 60 ), "minute" );
+	}
+
+	if( abs < 86400 ) {
+		return fmt.format( Math.trunc( sec / 3600 ), "hour" );
+	}
+
+	if( abs < 86400 * 30 ) {
+		return fmt.format( Math.trunc( sec / 86400 ), "day" );
+	}
+
+	if( abs < 86400 * 365 ) {
+		return fmt.format( Math.trunc( sec / ( 86400 * 30 ) ), "month" );
+	}
+
+	return fmt.format( Math.trunc( sec / ( 86400 * 365 ) ), "year" );
+}
+
+/**
+ * Events one after the other on a line, each with its icon in a round mark.
+ * The line from a mark to the next one is in the accent when the next event is done,
+ * dashed when the event it leaves is not done.
+ *
+ * @cssvar
+ * ```
+ * --timeline-done-color
+ * --timeline-done-icon-color
+ * --timeline-todo-color
+ * --timeline-todo-icon-color
+ * --timeline-title-color
+ * --timeline-text-color
+ * --timeline-time-color
+ * ```
+ */
+
+export class Timeline extends Component<TimelineProps, TimelineEvents> {
+	static classPrefix = "x4";
+
+	constructor( props: TimelineProps ) {
+		super( props );
+
+		this.setClass( "vertical", props.vertical ?? true );
+
+		this.mapPropEvents( props, "click" );
+		this.addDOMEvent( "click", ( ev ) => this._onClick( ev ) );
+
+		if( props.items ) {
+			this.setItems( props.items );
+		}
+	}
+
+	setItems( items: TimelineItem[] ) {
+		const renderer = this.props.renderer;
+
+		const content = items.map( ( item, i ) => {
+			const body = renderer ? renderer( item ) : [
+				new Component( { cls: "title", content: item.title } ),
+				item.text ? new Component( { cls: "text", content: item.text } ) : null,
+				item.date ? new Component( { cls: "time", content: relativeTime( item.date ) } ) : null,
+			];
+
+			const el = new Component( { cls: "item", content: [
+				new Component( { cls: "rail", content: [
+					new Component( { cls: "mark", content: new Icon( { iconId: item.icon } ) } ),
+					new Component( { cls: "line" } ),
+				] } ),
+				new Component( { cls: "content", content: body } ),
+			] } );
+
+			el.setClass( "done", !!item.done );
+			el.setClass( "next-done", i + 1 < items.length && !!items[i + 1].done );
+			el.setInternalData( "item", item );
+			return el;
+		} );
+
+		this.setContent( content );
+	}
+
+	/**
+	 * a click anywhere in an event: its item
+	 */
+
+	private _onClick( ev: MouseEvent ) {
+		const el = Component.closest( ev.target as Element, ".x4timeline > .item" );
+		if( el ) {
+			this.fire( "click", { context: el.getInternalData( "item" ) } );
+		}
+	}
+}

package/src/components/treeview/treeview.ts

@@ -16,7 +16,7 @@
 
 import { asap } from '../../core/core_tools';
 import { EventCallback } from '../../core/core_events';
-import { Component, ComponentEvent, ComponentEvents, ComponentProps, EvClick, EvDblClick, EvSelectionChange, componentFromDOM } from '../../core/component';
+import { Component, ComponentEvent, ComponentEvents, ComponentProps, EvClick, EvDblClick, EvSelectionChange } from '../../core/component';
 
 import { ScrollView, Viewport } from '../viewport/viewport';
 import { Label, SimpleText } from '../label/label';
@@ -244,30 +244,24 @@ export class Treeview extends Component<TreeviewProps,TreeviewEvents> {
 	}
 
 	private _on_click( ev: UIEvent ) {
-		let target = ev.target as HTMLElement;
-		
-		while( target && target!=this.dom ) {
-			const c = componentFromDOM( target );
-			
-			if( c && c.hasClass("item") ) {
-				const id = c.getInternalData( "id" );
-
-				const fev: ComponentEvent = { context:id };
-				if (ev.type == 'click') {
-					this.fire('click', fev );
-				}
-				else {
-					this.fire('dblClick', fev );
-				}
-
-				if (!fev.defaultPrevented) {
-					this._selectItem( id, c );
-				}
+		// an item of this tree, not of a component around it
+		const c = Component.closest( ev.target as Element, ".item" );
+		if( c && this.contains( c ) ) {
+			const id = c.getInternalData( "id" );
+
+			const fev: ComponentEvent = { context:id };
+			if (ev.type == 'click') {
+				this.fire('click', fev );
+			}
+			else {
+				this.fire('dblClick', fev );
+			}
 
-				return;
+			if (!fev.defaultPrevented) {
+				this._selectItem( id, c );
 			}
 
-			target = target.parentElement;
+			return;
 		}
 
 		this.clearSelection( );

package/src/core/component.ts

@@ -959,7 +959,24 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
      */
 
 	parentElement<T extends Component>( cls?: Constructor<T> ): T {
-		return Component.parentElement<T>( this.dom, cls );	
+		return Component.parentElement<T>( this.dom, cls );
+	}
+
+	/**
+	 * The nearest component whose element matches a css selector: this one, or one of its ancestors.
+	 * @returns null when there is none
+	 */
+
+	closest<T extends Component = Component>( selector: string ): T {
+		return Component.closest<T>( this.dom, selector );
+	}
+
+	/**
+	 * true when a node, or the element of a component, is the element of this one or inside it
+	 */
+
+	contains( other: Component | Node ): boolean {
+		return this.dom.contains( other instanceof Component ? other.dom : other );
 	}
 
 	/**
@@ -992,10 +1009,22 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 
 			dom = dom.parentElement;
 		}
-		
+
 		return null;
 	}
 
+	/**
+	 * The nearest component whose element matches a css selector: the one of dom, or one of its ancestors.
+	 * @returns null when there is none
+	 * @example
+	 * // in a click handler: the item hit, wherever the click is in it
+	 * const item = Component.closest( ev.target as Element, ".x4timeline > .item" );
+	 */
+
+	static closest<T extends Component = Component>( dom: Element, selector: string ): T {
+		return componentFromDOM<T>( dom.closest( selector ) );
+	}
+
 	/**
      * Returns the first child element as a Component instance.
      * @returns The first child component, or `null` if none exists.

package/src/core/core_shortcuts.ts

@@ -51,7 +51,8 @@ interface Keys {
 	key: string;
 }
 
-const isMac = /mac|iphone|ipad/i.test( navigator.platform ?? "" );
+/** true on a Mac, an iPhone or an iPad: Mod is Cmd there */
+export const isMac = /mac|iphone|ipad/i.test( navigator.platform ?? "" );
 
 /**
  * "Shift+Mod+K" -> shift, ctrl (cmd on a Mac), k