x4js 2.3.20 → 2.3.22

package/src/components/settingsview/settingsview.module.scss

@@ -0,0 +1,178 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file settingsview.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 {
+	--settingsview-toc-width: 210px;
+	--settingsview-section-background: var( --color-primary-a10 );
+	--settingsview-section-title-background: var( --color-primary-a20 );
+	--settingsview-hover-background: color-mix( in srgb, var( --color-primary-a20 ) 60%, transparent );
+	--settingsview-marker: var( --accent-background );
+}
+
+.x4settingsview {
+	min-height: 0;
+
+	> .search {
+		flex-shrink: 0;
+		padding: 12px 32px 12px calc( var( --settingsview-toc-width ) + 32px );
+		border-bottom: 1px solid var( --border );
+
+		> .x4input {
+			flex: 1;
+			max-width: 900px;
+			margin: 0;
+			padding: 6px 10px;
+			border: 1px solid var( --border );
+			border-radius: 4px;
+
+			&:focus {
+				border-color: var( --settingsview-marker );
+			}
+		}
+	}
+
+	> .body {
+		min-height: 0;
+		align-items: stretch;
+	}
+
+	// the summary: the section at the top in the color of the text, marked on its left
+	.toc {
+		flex-shrink: 0;
+		width: var( --settingsview-toc-width );
+		margin: 0;
+		padding: 12px 0;
+		border: none;
+		border-right: 1px solid var( --border );
+		border-radius: 0;
+		background: transparent;
+
+		.x4item {
+			padding: 4px 4px 4px 16px;
+			border-left: 2px solid transparent;
+			border-radius: 0;
+			--label-color: var( --text-secondary );
+
+			&:hover {
+				background: transparent;
+				--label-color: var( --text-primary );
+			}
+
+			&.selected {
+				background: transparent;
+				border-left-color: var( --settingsview-marker );
+				--label-color: var( --text-primary );
+				font-weight: 600;
+			}
+		}
+	}
+
+	.sections {
+		align-items: flex-start;
+		gap: 24px;
+		min-height: 0;
+		overflow-y: auto;
+		padding: 20px 32px 32px;
+
+		> .nomatch {
+			padding: 8px;
+			--label-color: var( --text-secondary );
+		}
+	}
+
+	// a section: a panel, its title on a band
+	.section {
+		flex-shrink: 0;
+		width: 100%;
+		max-width: 900px;
+		padding: 0 8px 10px;
+		border: 1px solid var( --border );
+		border-radius: 8px;
+		background: var( --settingsview-section-background );
+		overflow: hidden;
+		scroll-margin-top: 20px;	// brought to the top: below the padding of the view
+
+		// the last one shown: as high as the view, a click in the summary brings it to the top too
+		&.last {
+			min-height: 100%;
+		}
+
+		> .title {
+			margin: 0 -8px 6px;
+			padding: 12px 16px;
+			border-bottom: 1px solid var( --border );
+			background: var( --settingsview-section-title-background );
+			font-size: 1.1rem;
+			font-weight: 600;
+			--label-color: var( --text-primary );
+		}
+
+		> .description {
+			padding: 10px 8px 4px;
+			white-space: normal;
+			--label-color: var( --text-secondary );
+		}
+
+		// a section is as high as its content: what it holds takes its own height,
+		// a flex child (a Form) would get none
+		> * {
+			flex: none;
+		}
+
+		// a form of settings: the settings set the spaces
+		> .x4form {
+			padding: 0;
+		}
+	}
+
+	// a setting: its name, what it does, its controls; marked on its left while one has the focus
+	.x4settingitem {
+		flex-shrink: 0;
+		gap: 4px;
+		padding: 10px 8px 12px;
+		border-left: 2px solid transparent;
+		border-radius: 4px;
+
+		&:hover {
+			background: var( --settingsview-hover-background );
+		}
+
+		&:focus-within {
+			border-left-color: var( --settingsview-marker );
+		}
+
+		> .name {
+			font-weight: 600;
+			--label-color: var( --text-primary );
+		}
+
+		> .description {
+			white-space: normal;
+			--label-color: var( --text-secondary );
+		}
+
+		> .controls {
+			align-items: center;
+			gap: 10px;
+			padding-top: 4px;
+			flex-wrap: wrap;
+
+			> * {
+				margin: 0;
+			}
+		}
+	}
+}

package/src/components/settingsview/settingsview.ts

@@ -0,0 +1,289 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file settingsview.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 } from '../../core/component';
+import { EventCallback } from '../../core/core_events';
+import { class_ns } from '../../core/core_tools';
+
+import { BoxProps, HBox, VBox } from '../boxes/boxes';
+import { Input } from '../input/input';
+import { Label } from '../label/label';
+import { Listbox } from '../listbox/listbox';
+
+import { _tr } from '../../x4.js';
+
+import "./settingsview.module.scss"
+
+/**
+ *
+ */
+
+export interface SettingItemProps extends BoxProps {
+	title: string;
+	description?: string;
+	content: Component | Component[];	// its controls
+}
+
+/**
+ * one setting: its name, what it does, then its controls on a line that wraps.
+ * It has no value of its own: its controls keep theirs. To read and write them
+ * together, put the items in a Form and give the controls a name.
+ */
+
+@class_ns( "x4" )
+export class SettingItem extends VBox<SettingItemProps> {
+
+	constructor( props: SettingItemProps ) {
+		// the content goes under the name and the description, not in the box itself
+		super( { ...props, content: undefined } );
+
+		this.setContent( [
+			new Label( { cls: "name", text: props.title } ),
+			props.description ? new Label( { cls: "description", text: props.description } ) : null,
+			new HBox( { cls: "controls", content: props.content } ),
+		] );
+	}
+
+	/**
+	 * the text a search looks in: the name and the description
+	 */
+
+	getSearchText( ) {
+		return `${this.props.title} ${this.props.description ?? ""}`;
+	}
+}
+
+/**
+ * a section: a panel, its title on a band, then its content
+ */
+
+export interface SettingsSection {
+	id: string;
+	title: string;
+	description?: string;		// under the title
+	content: Component[];		// SettingItem, Form of SettingItem, or any component
+}
+
+export interface EvSectionChange extends ComponentEvent {
+	readonly section: string;	// the id of the section now at the top
+}
+
+export interface SettingsViewProps extends BoxProps {
+	sections?: SettingsSection[];
+	searchable?: boolean;			// a search field above the sections
+	searchPlaceholder?: string;		// _tr.global.settings.search when missing
+	noMatch?: string;				// shown when the search finds nothing; _tr.global.settings.nomatch when missing
+	sectionChange?: EventCallback<EvSectionChange>;
+}
+
+export interface SettingsViewEvents extends ComponentEvents {
+	sectionChange: EvSectionChange;
+}
+
+/**
+ * text compared without case nor accents
+ */
+
+function normalize( text: string ) {
+	return text.normalize( "NFD" ).replace( /[̀-ͯ]/g, "" ).toLowerCase( );
+}
+
+/**
+ * a page of settings, as the settings of VS Code: the summary of the sections
+ * on the left, the sections on the right, one after the other. A click in the
+ * summary brings its section to the top; the summary follows the scroll.
+ * With searchable, a field above them filters the settings.
+ *
+ * @cssvar
+ * ```
+ * --settingsview-toc-width
+ * --settingsview-section-background
+ * --settingsview-section-title-background
+ * --settingsview-hover-background
+ * --settingsview-marker
+ * ```
+ */
+
+@class_ns( "x4" )
+export class SettingsView<P extends SettingsViewProps = SettingsViewProps> extends VBox<P,SettingsViewEvents> {
+
+	// fields, not refs: refs belong to the classes that derive from this one
+	private _search: Input = null;
+	private _toc: Listbox;
+	private _view: VBox;
+	private _noMatch: Label;
+
+	// shown: kept by the search (isVisible is false too while the view is hidden)
+	private _sections: { section: SettingsSection, box: VBox, shown: boolean }[] = [];
+	private _current = "";		// the id of the section at the top
+
+	constructor( props: P ) {
+		super( props );
+		this.mapPropEvents( props, "sectionChange" );
+
+		this.setContent( [
+			props.searchable ? new HBox( {
+				cls: "search",
+				content: this._search = new Input( {
+					type: "text",
+					placeholder: props.searchPlaceholder ?? _tr.global.settings.search,
+					change: ( ) => this._filter( ),
+				} ),
+			} ) : null,
+
+			new HBox( {
+				cls: "body",
+				flex: true,
+				content: [
+					this._toc = new Listbox( {
+						cls: "toc",
+						items: [],
+						selectionChange: ( ev ) => this.showSection( ev.selection[0] as string ),
+					} ),
+					this._view = new VBox( { cls: "sections", flex: true } ),
+				],
+			} ),
+		] );
+
+		this._noMatch = new Label( { cls: "nomatch", text: props.noMatch ?? _tr.global.settings.nomatch, hidden: true } );
+		this._view.addDOMEvent( "scroll", ( ) => this._followScroll( ) );
+
+		// Escape empties the search
+		if( this._search ) {
+			this._search.addDOMEvent( "keydown", ( ev ) => {
+				if( ev.key == "Escape" && this._search.getValue( ) ) {
+					this._search.setValue( "" );
+					this._filter( );
+				}
+			} );
+		}
+
+		if( props.sections ) {
+			this.setSections( props.sections );
+		}
+	}
+
+	/**
+	 * the sections, in their order; for a class that builds them in its
+	 * constructor, after super( )
+	 */
+
+	setSections( sections: SettingsSection[] ) {
+		this._sections = sections.map( section => ( {
+			section,
+			shown: true,
+			box: new VBox( {
+				cls: "section",
+				content: [
+					new Label( { cls: "title", text: section.title } ),
+					section.description ? new Label( { cls: "description", text: section.description } ) : null,
+					...section.content,
+				],
+			} ),
+		} ) );
+
+		this._view.setContent( [ ...this._sections.map( s => s.box ), this._noMatch ] );
+		this._current = "";
+		this._filter( );
+	}
+
+	/**
+	 * brings a section to the top of the view
+	 */
+
+	showSection( id: string, smooth = true ) {
+		this._sections.find( s => s.section.id == id )?.box.scrollIntoView( { behavior: smooth ? "smooth" : "auto", block: "start" } );
+	}
+
+	/**
+	 * the id of the section at the top of the view
+	 */
+
+	getSection( ) {
+		return this._current;
+	}
+
+	/**
+	 * shows what the search finds; everything when it is empty. A section
+	 * whose title or description holds the words is shown whole; otherwise
+	 * only its settings that hold them, and what holds those settings.
+	 */
+
+	private _filter( ) {
+		const text = this._search ? this._search.getValue( ) : "";
+		const words = normalize( text ).split( /\s+/ ).filter( w => w );
+		const matches = ( text: string ) => {
+			const t = normalize( text );
+			return words.every( w => t.includes( w ) );
+		};
+
+		let found = false;
+		for( const s of this._sections ) {
+			const { section, box } = s;
+			const whole = !words.length || matches( `${section.title} ${section.description ?? ""}` );
+			let shown = whole;
+
+			for( const c of section.content ) {
+				const items = c instanceof SettingItem ? [c] : c.enumChildComponents( true ).filter( x => x instanceof SettingItem ) as SettingItem[];
+				let some = false;
+				for( const item of items ) {
+					const ok = whole || matches( item.getSearchText( ) );
+					item.show( ok );
+					some ||= ok;
+				}
+				// what holds no setting (a table, a text) is shown with its whole section only
+				c.show( whole || some );
+				shown ||= some;
+			}
+
+			s.shown = shown;
+			box.show( shown );
+			found ||= shown;
+		}
+
+		this._noMatch.show( !found );
+
+		// the summary lists the sections shown; the last one is as high as the
+		// view at least: a click in the summary can bring every section to the top
+		const shown = this._sections.filter( s => s.shown );
+		this._sections.forEach( s => s.box.setClass( "last", s == shown[shown.length - 1] ) );
+		this._toc.clearSelection( false );
+		this._toc.setItems( shown.map( s => ( { id: s.section.id, text: s.section.title } ) ) );
+		this._current = "";
+		this._followScroll( );
+	}
+
+	/**
+	 * the summary on the section at the top of the view; the first one while the view is hidden
+	 */
+
+	private _followScroll( ) {
+		const view = this._view.getBoundingRect( );
+
+		let current = "";
+		for( const { section, box, shown } of this._sections ) {
+			if( shown && ( !current || ( view.height && box.getBoundingRect( ).top <= view.top + 40 ) ) ) {
+				current = section.id;
+			}
+		}
+
+		this._toc.select( current, false );
+		if( current != this._current ) {
+			this._current = current;
+			this.fire( "sectionChange", { section: current } );
+		}
+	}
+}

package/src/components/spreadsheet/spreadsheet.module.scss

@@ -16,30 +16,31 @@
 
 
 :root {
-	--spreadsheet-background: white;
+	// from the theme: a dark theme (its scale --color-primary-* reversed) gives a dark grid
+	--spreadsheet-background: var( --background-primary );
 	--spreadsheet-border: var( --border );
 	
-	--spreadsheet-header-cell-background: white;
-	--spreadsheet-header-cell-color: black;
-	--spreadsheet-header-cell-vline: #f0f0f0;
-	--spreadsheet-header-cell-border: #cccccc;
+	--spreadsheet-header-cell-background: var( --background-primary );
+	--spreadsheet-header-cell-color: var( --text-primary );
+	--spreadsheet-header-cell-vline: var( --border );
+	--spreadsheet-header-cell-border: var( --border );
 
 	--spreadsheet-check-background: var( --accent-background );
-	--spreadsheet-check-color: white;
-	--spreadsheet-check-background-hover: white;
+	--spreadsheet-check-color: var( --accent-color );
+	--spreadsheet-check-background-hover: var( --background-primary );
 	--spreadsheet-check-color-hover: var( --accent-background );
 
 	--spreadsheet-perc-background: var( --accent-background );
-	--spreadsheet-perc-color: white;
-	--spreadsheet-perc-background-hover: white;
+	--spreadsheet-perc-color: var( --accent-color );
+	--spreadsheet-perc-background-hover: var( --background-primary );
 	--spreadsheet-perc-color-hover: var( --accent-background );
 
-	--spreadsheet-cell-color: black;
-	--spreadsheet-cell-color-sel: white;
+	--spreadsheet-cell-color: var( --text-primary );
+	--spreadsheet-cell-color-sel: var( --accent-color );
 	--spreadsheet-cell-vline: var( --border );
 
-	--spreadsheet-row-background: white;
-	--spreadsheet-row-odd-background: white;
+	--spreadsheet-row-background: var( --background-primary );
+	--spreadsheet-row-odd-background: var( --background-primary );
 	--spreadsheet-row-border: var( --border );
 
 	--spreadsheet-row-background-hover: var( --background-secondary );
@@ -70,6 +71,7 @@
 
 	background-color: var( --spreadsheet-background );
 	border: 1px solid var( --spreadsheet-border );
+	color: var( --spreadsheet-cell-color );
 		
 	.cell {
 		padding: 4px;
@@ -180,7 +182,7 @@
 				width: 100%;
 				border: 1px solid var( --border );
 				height: 8px;
-				background-color: white;
+				background-color: var( --spreadsheet-background );
 				overflow: hidden;
 
 				div {
@@ -234,7 +236,7 @@
 		display: inline-flex;
 		align-items: center;
 
-		color: black;
+		color: var( --spreadsheet-header-cell-color );
 		font-weight: 500;
 		justify-content: center;
 
@@ -307,7 +309,7 @@
 		width: var( --fixed-width );
 		bottom: 0;
 		
-		background-color: white;
+		background-color: var( --spreadsheet-background );
 		z-index: 1;
 
 		.row {

package/src/components/textarea/textarea.module.scss

@@ -27,6 +27,12 @@
 		flex-shrink: 0;		// alone in a box, it keeps its height: the box does not crush it
 		resize: none;		// no handle unless the prop resize asks for one
 		padding: 4px;
+
+		// never smaller than one character, its padding and border included (border-box):
+		// 10px = 2 x 4px of padding + 2 x 1px of border
+		min-height: calc( 1lh + 10px );
+		min-width: calc( 1ch + 10px );
+
 		outline: none;
 		font: inherit;
 
@@ -65,7 +71,8 @@
 	}
 
 	.x4simpletextarea {
-		@extend %flex;
-
-	}	
+		// its height of rows when the TextArea has none, the TextArea's height when it has one;
+		// a basis of 0 would leave it the height of its padding: a textarea scrolls, its min-height is 0
+		flex: 1 0 auto;
+	}
 }

package/src/components/video/video.ts

@@ -14,7 +14,9 @@
  * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
  **/
 
-import { Box, Component, ComponentProps } from 'x4js';
+import { Component, ComponentProps } from '../../core/component';
+import { class_ns } from '../../core/core_tools';
+import { Box } from '../boxes/boxes';
 
 import "./video.module.scss"
 
@@ -29,6 +31,7 @@ interface VideoProps extends ComponentProps {
  * 
  */
 
+@class_ns( "x4" )
 export class Video extends Box {
 	
 	private _vplayer: HTMLVideoElement;
@@ -124,7 +127,18 @@ export class Video extends Box {
 		this.player.pause( );
 	}
 
-	play( ) {
-		this.player.play( );
+	/**
+	 * @returns false when the playback could not start: the browser wants a click
+	 * of the user first, or the source cannot be played
+	 */
+
+	async play( ): Promise<boolean> {
+		try {
+			await this.player.play( );
+			return true;
+		}
+		catch( e ) {
+			return false;
+		}
 	}
 }

package/src/core/core_colors.ts

@@ -83,8 +83,6 @@ export class Color {
 
 	setValue(value: string): this {
 
-		this.invalid = false;
-
 		if( value.startsWith('#') ) {
 			if (value.length == 7 && /#[0-9a-fA-F]{6}/.test(value)) {
 				const hex = parseInt(value.slice(1), 16);
@@ -139,8 +137,10 @@ export class Color {
 			}
 		}
 
+		// red, to be seen, and marked as invalid
+		this.setRgb(255, 0, 0, 1);
 		this.invalid = true;
-		return this.setRgb(255, 0, 0, 1);
+		return this;
 	}
 
 	/**
@@ -205,23 +205,34 @@ export class Color {
 	 * @param r - Red component (0-255).
 	 * @param g - Green component (0-255).
 	 * @param b - Blue component (0-255).
-	 * @param a - Alpha component (0-1).
+	 * @param a - Alpha component (0-1, default 1.0).
 	 * @returns The current Color instance.
 	 */
-	setRgb(r: number, g: number, b: number, a: number): this {
-		this.rgb = [clamp(r | 0, 0, 255), clamp(g | 0, 0, 255), clamp(b | 0, 0, 255), clamp(a, 0, 1)];
+	setRgb(r: number, g: number, b: number, a = 1.0): this {
+		// a new color: valid
+		this.invalid = false;
+		// rounded: hsv gives 123.999 for 124; "| 0" makes a NaN 0
+		const c = ( v: number ) => clamp( Math.round( v ) | 0, 0, 255 );
+		this.rgb = [c(r), c(g), c(b), clamp(a, 0, 1)];
 		return this;
 	}
 
 	/**
 	 * Returns the CSS string representation of the color.
 	 * 
-	 * @param withAlpha - Whether to include the alpha channel (default: true if alpha < 1).
-	 * @returns The CSS color string (e.g. "rgb(255,0,0)" or "rgba(255,0,0,0.5)").
+	 * @param withAlpha - false (default): never the alpha; true: the alpha when the color is not opaque.
+	 * @returns The CSS color string (e.g. "rgb(255,0,0)" or "rgba(255,0,0,0.500)").
 	 */
-	toRgbString(withAlpha?: boolean): string {
+	toRgbString(withAlpha = false): string {
 		const _ = this.rgb;
-		return withAlpha === false || _[3] == 1 ? `rgb(${round(_[0])},${round(_[1])},${round(_[2])})` : `rgba(${round(_[0])},${round(_[1])},${round(_[2])},${_[3].toFixed(3)})`
+		const rgb = `${round(_[0])},${round(_[1])},${round(_[2])}`;
+
+		// an opaque color has no alpha to show
+		if( !withAlpha || _[3] >= 1 ) {
+			return `rgb(${rgb})`;
+		}
+
+		return `rgba(${rgb},${_[3].toFixed(3)})`;
 	}
 
 	/**

package/src/core/core_dragdrop.ts

@@ -175,12 +175,13 @@ class DragManager {
 	 */
 
 	private _startCheck() {
+		clearInterval( this.timer );
 
-		if (this.timer) {
-			clearInterval(this.timer);
-			this._check( );
-		}
+		// the target is told at once (and the one that was left)
+		this._check( );
 
+		// then checked again: over the children of a target, dragleave and dragover come
+		// in turn; it is left when no dragover came back in between
 		this.timer = setInterval( () => this._check(), 300 );
 	}