x4js 2.0.28 → 2.0.30

package/src/components/boxes/boxes.ts

@@ -14,18 +14,20 @@
  * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
  **/
 
-import { asap, class_ns, isArray, isNumber, isString } from '../../core/core_tools';
-import { Component, ComponentContent, ComponentEvents, ComponentProps, EvSelectionChange } from "../../core/component"
+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 "./boxes.module.scss";
-import { EventCallback } from '../../core/core_events';
 
 export interface BoxProps extends ComponentProps {
+	/** Optional HTML tag to use for the box. */
 	tag?: string;
 }
 
 /**
- * 
+ * A generic container component for grouping and laying out child components.
+ * The CSS class for this component is automatically generated as `x4box`.
  */
 
 @class_ns( "x4" )
@@ -34,7 +36,9 @@ export class Box<P extends BoxProps=BoxProps,E extends ComponentEvents=Component
 
 
 /**
- * 
+ * A horizontal box layout component.
+ * Arranges child components in a horizontal line.
+ * The CSS class for this component is automatically generated as `x4hbox`.
  */
 
 @class_ns( "x4" )
@@ -42,7 +46,9 @@ export class HBox<P extends BoxProps=BoxProps,E extends ComponentEvents=Componen
 }
 
 /**
- * 
+ * A vertical box layout component.
+ * Arranges child components in a vertical stack.
+ * The CSS class for this component is automatically generated as `x4vbox`.
  */
 
 @class_ns( "x4" )
@@ -53,42 +59,53 @@ export class VBox<P extends BoxProps=BoxProps,E extends ComponentEvents=Componen
 }
 
 
+type ContentBuilder = ( ) => Component;
+
+
 /**
- * stack of widgets where only one widget is visible at a time
+ * Represents an item in a {@link StackBox}.
  */
 
-type ContentBuilder = ( ) => Component;
-
 interface StackItem {
+	/** Unique name for the stack item. */
 	name: string;
+	/** Content of the stack item, either a component or a builder function. */
 	content: Component | ContentBuilder;
 	title?: string;
 }
 
 /**
- * 
+ * Events specific to the {@link StackBox} component.
  */
 
 interface StackeBoxEvents extends ComponentEvents {
+	/** Fired when the current page changes. */
 	pageChange?: EvSelectionChange;
 }
 
+/**
+ * Properties for the {@link StackBox} component.
+ */
+
 export interface StackBoxProps extends Omit<ComponentProps,"content"> {
+	/** Name of the default page to display. */
 	default: string;
+
+	/** List of stack items. */
 	items: StackItem[];
+
+	/** Callback for page change events. */
 	pageChange?: EventCallback<EvSelectionChange>;
 }
 
-/**
- * 
- */
 
 interface StackItemEx extends StackItem {
 	page: Component;
 }
 
 /**
- * 
+ * A stack of widgets where only one widget is visible at a time.
+ * The CSS class for this component is automatically generated as `x4stackbox`.
  */
 
 @class_ns( "x4" )
@@ -114,6 +131,11 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 		}
 	}
 
+	/**
+     * Adds a new item to the stack.
+     * @param item - The item to add.
+     */
+
 	addItem( item: StackItem ) {
 		this._items.push( {
 			name: item.name,
@@ -122,6 +144,11 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 		});
 	}
 
+	/**
+     * Removes an item from the stack by its name.
+     * @param name - The name of the item to remove.
+     */
+
 	removeItem( name: string ) {
 		const index = this._items.findIndex( x => x.name==name );
 		if( index>=0 ) {
@@ -134,10 +161,17 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 		}
 	}
 
+	/**
+     * Selects a page by its name.
+     * @param name - The name of the page to select.
+     * @returns The selected page component, if any.
+     */
+	
 	select( name: string ) {
 		let sel = this.query( `:scope > .selected` );
 		if( sel ) {
 			sel.setClass( "selected", false );
+			(sel as any).deactivate?.( );
 		}
 
 		this._cur = this._items.findIndex( x => x.name==name );
@@ -181,8 +215,10 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 	}
 
 	/**
-	 * 
-	 */
+     * Retrieves a page by its name.
+     * @param name - The name of the page to retrieve.
+     * @returns The page content, if found.
+     */
 	
 	getPage( name: string ) {
 		const pg = this._items.find( x => x.name==name );
@@ -190,24 +226,28 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 	}
 
 	/**
-	 * 
-	 */
+     * Gets the total number of pages in the stack.
+     * @returns The number of pages.
+     */
 
 	getPageCount( ) {
 		return this._items.length;
 	}
 
 	/**
-	 * 
-	 */
+     * Enumerates the names of all pages in the stack.
+     * @returns An array of page names.
+     */
 
 	enumPageNames( ) {
 		return this._items.map( x => x.name );
 	}
 
 	/**
-	 * 
-	 */
+     * Retrieves a stack item by its name.
+     * @param name - The name of the item to retrieve.
+     * @returns The stack item, if found.
+     */
 
 	getItem( name: string ) {
 		const pg = this._items.find( x => x.name==name );
@@ -215,8 +255,9 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 	}
 
 	/**
-	 * 
-	 */
+     * Gets the name of the currently selected page.
+     * @returns The name of the current page, if any.
+     */
 
 	getCurPage( ) {
 		const c = this._items[this._cur];
@@ -227,8 +268,19 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
 // :: ASSIST BOX ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 
+/**
+ * A specialized stack box for assisted navigation, such as wizards or carousels.
+ * The CSS class for this component is automatically generated as `x4assistbox`.
+ */
+
 @class_ns( "x4" )
 export class AssistBox extends StackBox {
+
+	/**
+     * Selects the next or previous page in the stack.
+     * @param nxt - If `true`, selects the next page; otherwise, selects the previous page.
+     */
+
 	selectNextPage( nxt = true ) {
 		let p;
 		if( nxt && this._cur<this._items.length-1 ) {
@@ -243,10 +295,20 @@ export class AssistBox extends StackBox {
 		}
 	}
 
+	/**
+     * Checks if the current page is the first page.
+     * @returns `true` if the current page is the first page.
+     */
+
 	isFirstPage( ) {
 		return this._cur==0;
 	}
 
+	/**
+     * Checks if the current page is the last page.
+     * @returns `true` if the current page is the last page.
+     */
+
 	isLastPage( ) {
 		return this._cur==this._items.length-1;
 	}
@@ -268,6 +330,11 @@ export interface GridBoxProps extends Omit<BoxProps,"content"> {
 	items?: GridBoxItem[];
 }
 
+/**
+ * Grid-based layout container.
+ * Auto-generates CSS class: `x4gridbox`.
+ */
+
 @class_ns("x4")
 export class GridBox<P extends GridBoxProps=GridBoxProps,E extends ComponentEvents=ComponentEvents> extends Box<P,E> {
 
@@ -287,6 +354,11 @@ export class GridBox<P extends GridBoxProps=GridBoxProps,E extends ComponentEven
 		}
 	}
 
+	/**
+     * Sets grid rows (e.g., `2`, `"1fr 2fr"`, `["1fr", "2fr"]`).
+     * @param r - Rows definition.
+     */
+
 	setRows( r: number | string | string[] ) {
 		if( isArray(r) ) {
 			r = r.join( " " );
@@ -298,6 +370,11 @@ export class GridBox<P extends GridBoxProps=GridBoxProps,E extends ComponentEven
 		this.setStyleValue( "gridTemplateRows", r );
 	}
 
+	/**
+     * Sets grid columns (e.g., `3`, `"1fr 1fr"`, `["auto", "1fr"]`).
+     * @param r - Columns definition.
+     */
+
 	setCols( r: number | string | string[] ) {
 		if( isArray(r) ) {
 			r = r.join( " " );
@@ -309,23 +386,38 @@ export class GridBox<P extends GridBoxProps=GridBoxProps,E extends ComponentEven
 		this.setStyleValue( "gridTemplateColumns", r );
 	}
 
+	/**
+     * Sets the number of rows.
+     * @param n - Row count.
+     */
+
 	setRowCount( n: number ) {
 		this.setStyleValue( "gridTemplateRows", `repeat(${n})` );
 	}
 
+	/**
+     * Sets the number of columns.
+     * @param n - Column count.
+     */
+
 	setColCount( n: number ) {
 		this.setStyleValue( "gridTemplateColumns", `repeat(${n})` );
 	}
 
 	/**
-	 * @param t "a a a" "b c c" "b c c"
-	 * user item.setAttribute( "grid-area", "a" );
-	 */
+     * Sets grid template areas (e.g., `["a a", "b c"]`).
+     * @param t - Template strings.
+     */
 
 	setTemplate( t: string[] ) {
 		this.setAttribute( "grid-template-area", t.map( x => '"' + x + '"' ).join(" ") );
 	}
 
+	/**
+     * Places items at specific grid positions.
+     * @param items - Array of `{row, col, item}`.
+     */
+
 	setItems( items: GridBoxItem[] ) {
 		items.forEach( x => {
 			x.item.setStyle( {
@@ -348,6 +440,11 @@ interface MasonryProps extends Omit<BoxProps,"content"> {
 	items: Component[];
 }
 
+/**
+ * Masonry-style layout (Pinterest-like).
+ * Auto-generates CSS class: `x4masonrybox`.
+ */
+
 @class_ns("x4")
 export class MasonryBox extends Box<MasonryProps> {
 
@@ -363,6 +460,11 @@ export class MasonryBox extends Box<MasonryProps> {
 		}
 	}
 
+	/**
+     * Resizes a single masonry item.
+     * @param item - Item to resize.
+     */
+
 	resizeItem(item: Component) {
 		const style = this.getComputedStyle();
 
@@ -381,13 +483,22 @@ export class MasonryBox extends Box<MasonryProps> {
 		}
 	}
 	  
+	/**
+     * Resizes all items to fit the grid.
+     */
+
 	resizeAllItems( ) {
 		const els = this.queryAll( ".item" );
-		els.forEach( itm => {;
+		els.forEach( itm => {
 			this.resizeItem( itm );
 		} );
 	}
 
+	/**
+     * Sets masonry items.
+     * @param items - Array of components.
+     */
+
 	setItems( items: Component[] ) {
 		const els = items.map( x => {
 			return new Box( {

package/src/components/button/button.ts

@@ -14,11 +14,11 @@
  * 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 { class_ns, UnsafeHtml } from '../../core/core_tools';
+import { Component, ComponentEvents, ComponentProps, EvClick } from "../../core/component.ts"
+import { EventCallback } from '../../core/core_events.ts';
+import { class_ns, UnsafeHtml } from '../../core/core_tools.ts';
 
-import { Icon } from "../icon/icon"
+import { Icon } from "../icon/icon.ts"
 
 import "./button.module.scss";
 
@@ -28,6 +28,11 @@ import "./button.module.scss";
  */
 
 interface ButtonEvents extends ComponentEvents {
+	/** 
+	 * Fired when the button is clicked 
+	 * ex: myButton.on( "click", ( e: EvClick ) => { console.log( "click") } );
+	 */
+
 	click: EvClick;
 }
 
@@ -36,29 +41,62 @@ interface ButtonEvents extends ComponentEvents {
  */
 
 export interface ButtonProps extends ComponentProps {
-	label?: string;
+	/** Text or HTML content of the button */
+	label?: string | UnsafeHtml;	
+
+	/** Icon identifier to display */
 	icon?: string;
+
+	/** 
+	 * Tab index for keyboard navigation.
+	 * - `false` to exclude from tab order
+	 * - `number` to set specific tab index
+	 */
 	tabindex?: boolean | number;
+	
+	/** 
+	 * Enable auto-repeat behavior when button is held down.
+	 * - `true` uses default 200ms repeat interval
+	 * - `number` specifies custom repeat interval in milliseconds
+	 * 
+	 * First click triggers after 500ms, then repeats at specified interval.
+	 */
 	autorepeat?: number | boolean;
+
+	/**
+	 * Callback function invoked when button is clicked 
+	 * cf. ButtonEvents
+	 */
 	click?: EventCallback<EvClick>;
 }
 
 /**
- * Button component.
+ * Represents a clickable button component.
+ * 
+ * Generates the CSS class **x4button** based on the class name.
+ * The button can contain an optional icon and label, supports keyboard activation,
+ * and may trigger auto-repeated click events while pointer is held down.
+ * 
  */
 
+
 @class_ns( "x4" )
 export class Button extends Component<ButtonProps,ButtonEvents> {
 
 	#text: Component;
 
 	/**
-     * Creates an instance of Button.
-     * 
-     * @param props - The properties for the button component, including label and icon.
-     * @example
-     * const button = new Button({ label: 'Submit', icon: 'check-icon' });
-     */
+	 * Create a new Button.
+	 *
+	 * @param {ButtonProps} props - Configuration options such as `label`, `icon`, `tabindex`, `autorepeat`, and `click`.
+	 *
+	 * @example
+	 * const btn = new Button({
+	 *   label: "Save",
+	 *   icon: "check",
+	 *   click: () => console.log("clicked"),
+	 * });
+	 */
 
 	constructor( props: ButtonProps ) {
 		super( { ...props, tag: 'button', content: null } );
@@ -88,7 +126,7 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 	}
 
 	/**
-	 * called by the system on click event
+	 * @internal 
 	 */
 
 	protected _on_click( ev: MouseEvent ) {
@@ -109,6 +147,10 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 		ev.stopPropagation();
 	}
 
+	/**
+	 * @internal
+	 */
+
 	protected _on_mouse( e: PointerEvent ) {
 
 		let count = 0;
@@ -119,11 +161,10 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 			const rt = this.props.autorepeat===true ? 200 : this.props.autorepeat as number;
 
 			this.setTimeout( 'repeat', 500, ( ) => {
-				count++;
-
-				this.fire('click', {} );
+				this.fire( "click", {} );
 				this.setInterval( 'repeat', rt, ( ) => {
-					this.fire('click', {} );
+					count++;
+					this.fire( "click", {repeat:count} );
 				})
 			} );
 		}
@@ -131,13 +172,16 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 			this.clearTimeout( 'repeat' );
 
 			if( !count ) {
-				this.fire('click', {} );
+				this.fire("click", {} );
 			}
 		}
 	}
 
 	/**
-	 * simulate a click
+	 * Activate the button as if it was clicked by a user.
+	 *
+	 * @example
+	 * button.click();
 	 */
 
 	click( ) {
@@ -145,7 +189,7 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 	}
 
 	/**
-	 * called on key down
+	 * @internal
 	 */
 
 	protected _on_keydown( e: KeyboardEvent ) {
@@ -156,13 +200,15 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 	}
 
 	/**
-     * Sets the text content of the button's label.
-     * 
-     * @param text - The new text or HTML content for the label.
-     * @example
-     * button.setText('Click Me');
-     * button.setText(new UnsafeHtml('<b>Bold Text</b>'));
-     */
+	 * Set or change the button label.
+	 *
+	 * @param {string | UnsafeHtml} text - Text content or unsafe HTML.
+	 *
+	 * @example
+	 * button.setText("Confirm");
+	 * button.setText(new UnsafeHtml("<strong>OK</strong>"));
+	 * button.setText( unsafe`<strong>OK</strong>` );
+	 */
 
 	public setText( text: string | UnsafeHtml ) {
 		this.#text.setContent( text );
@@ -170,12 +216,13 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 	}
 	
 	/**
-     * Sets the icon of the button.
-     * 
-     * @param icon - The new icon ID to set on the button.
-     * @example
-     * button.setIcon('new-icon-id');
-     */
+	 * Set or change the icon displayed by the button.
+	 *
+	 * @param {string} icon - Icon identifier to associate with the button.
+	 *
+	 * @example
+	 * button.setIcon("arrow-right");
+	 */
 
 	public setIcon( icon: string ) {
 		this.query<Icon>( "#icon" ).setIcon( icon );

package/src/components/combobox/combobox.ts

@@ -52,7 +52,6 @@ export class DropdownList extends Popup<DropdownProps,DropdownEvents> {
 		this.setContent( this._list );
 
 		this.addDOMEvent( "mousedown", ( ev: Event ) => { 
-			console.log( "trap" );
 			ev.stopImmediatePropagation( );
 			ev.stopPropagation( );
 			ev.preventDefault( );
@@ -228,6 +227,7 @@ export class Combobox extends Component<ComboboxProps,ComboboxEvents> {
 		const rc = this._edit.getBoundingRect( );
 		this._popup.setStyleValue( "minWidth", rc.width+"px" );
 		this._popup.displayNear( rc, "top left", "bottom left", {x:0,y:6} );
+		this._popup.getList().ensureSelectionVisible( );
 	}
 
 	setItems( items: ListItem[] ) {

package/src/components/dialog/dialog.ts

@@ -183,6 +183,10 @@ export class Dialog<P extends DialogProps = DialogProps, E extends DialogEvents
 		return this.form.getValues();
 	}
 
+	validate( ) {
+		return this.form.validate( );
+	}
+
 	/**
 	 * 
 	 */