x4js 2.3.24 → 2.3.25

package/aicontext.md

@@ -91,6 +91,8 @@ fire<K>(name: K, ev: E[K]): void
 
 - `capturing = true` inserts at the head of the listener list.
 - `fire()` automatically injects `source`, `type`, `stopPropagation()`, `preventDefault()` when absent.
+- A listener that throws: `fire()` sends its error to `console.error`, calls the next listeners, and returns
+  normally; the one that fires never gets the error of a listener. (An `async` listener rejects its own promise.)
 
 ### `CoreEvent`
 
@@ -140,7 +142,7 @@ interface ComponentProps {
   flex?: number | boolean                            // true → "x4flex"; number → flex-grow
   disabled?: boolean
   hidden?: boolean
-  tooltip?: string
+  tooltip?: string                                   // shown as html: escape a text from a user (see initTooltips)
   existingDOM?: HTMLElement                          // wrap an existing DOM node
 }
 
@@ -220,7 +222,8 @@ 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
+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
 ```
 
 ### Visibility / state / focus / geometry
@@ -312,6 +315,9 @@ interface BoxProps extends ComponentProps { tag?: string }
 
 ### `Box.refs` — typed directory of the children to reach again later
 
+Only a `Box` has `refs`: a class derived from `Component` (not from `Box`) has none, and `this.refs.x = ...` there
+compiles with a `declare refs` but throws a `TypeError` at run time.
+
 `Box` owns a `protected refs: Record<string, Component>`. Declare its shape in the subclass, then assign each child
 to `refs` while building the content: the assignment evaluates to the component, so it is written inline in the
 content array. Do not keep such children in separate private fields, and do not use `refs.x` for a child that was
@@ -826,29 +832,46 @@ class FileDialog extends Component {}      // programmatic file picker
 interface ListItem {
   id: ListboxID                            // number | string
   text: string | UnsafeHtml
-  iconId?: string; data?: any; cls?: string; checked?: boolean
+  sub_cols?: (string | UnsafeHtml | Component)[]   // extra columns after text (9 at most, ref-c2...ref-c10, see Header);
+                                           // a null value makes no cell. A Treeview draws them too
+  iconId?: string; data?: any; cls?: string
+  checked?: boolean                        // checkable: the starting state of the case (getChecked() gives the current one)
 }
 interface ListboxProps extends Omit<ComponentProps,"content"> {
   items?: ListItem[]
   renderer?: (item: ListItem) => Component
   title?: string; icon?: string
   header?: Header; footer?: Component
-  checkable?: true; multisel?: true
+  checkable?: boolean                      // a case at the start of each line
+  multisel?: true
+  reselect?: boolean                       // a click on the item already selected fires selectionChange again
+                                           // (lists linked together: the view shows what was clicked last)
   emptyMsg?: string                        // shown in place of the items while there are none
   dblClick?: EventCallback<EvDblClick>
   selectionChange?: EventCallback<EvSelectionChange>
   contextMenu?: EventCallback<EvContextMenu>
+  checkChange?: EventCallback<EvCheckChange>   // EvCheckChange { id: ListboxID, checked: boolean }
 }
 // emptyMsg: without it the text is _tr.global.empty_list ("Empty list"). It is shown by setItems
 //   (the constructor calls it) when there is no item. The listbox then has the class "empty".
+// click: no prop; listbox.on( "click", ev => ... ), ev.context the id of the item. It is fired on the item
+//   already selected too, which fires no selectionChange.
+// checkable: renderItem puts the case (.x4check) first in the line, with a renderer of yours too;
+//   a checked line has the class "checked". A click on the case, or Space for the last item
+//   selected, changes it and fires checkChange: no click, no selection. A double click on the
+//   case is ignored (its two clicks change it twice). setChecked fires nothing; updateItem keeps
+//   the state of the case. With a header, the columns start after the case.
 class Listbox extends Component {
-  setItems(items: ListItem[], keepSel?: boolean): void
+  setItems(items: ListItem[], keepSel?: boolean): void   // one selectionChange at the end, with the selection it ends
+                                           // with, when there was one before or there is one after (keepSel: the same ids too)
   appendItem(item: ListItem, prepend?: boolean, select?: boolean): void
   updateItem(id: any, item: ListItem): void
   getItem(id: ListboxID): ListItem
   select(ids: ListboxID | ListboxID[], notify?: boolean): void
   clearSelection(fireEvent?: boolean): void
   getSelection(): ListboxID[]
+  getChecked(): ListboxID[]                // checkable: in the order of the list
+  setChecked(ids: ListboxID[]): void       // these checked, the others not; no event
   filter(filter: string | RegExp): void
   navigate(sens: kbNav): boolean
   ensureSelectionVisible(): void
@@ -1036,6 +1059,7 @@ interface ButtonProps extends ComponentProps {
   menu?: MenuElement[] | (() => MenuElement[])   // a click opens this Menu under the button, in place of the click event;
                                            // a function is called at each click; the button gets the class "with-menu"
 }
+// its <button> is type="button": in a <form>, Enter in a field does not click it. attrs: { type: "submit" } to submit
 class Button extends Component {
   click(): void                            // simulate a click
   setText(text: string|UnsafeHtml): void
@@ -1078,6 +1102,8 @@ class Popup extends Box {
   isOpen(): boolean
   // show()/hide() inherited from Component; show() routes to displayCenter()
 }
+// A modal popup (a Dialog, a MessageBox...) keeps the element that had the focus when it opens and gives
+// it back the focus when it closes, unless the focus was put elsewhere meanwhile.
 ```
 
 ### `Dialog`
@@ -1101,6 +1127,10 @@ class Dialog extends Popup {
   show(): this                             // each time: the focus on its first field
   showAsync(): Promise<string>             // the name of the clicked button; null when closed without a button (Escape, close box)
 }
+// Keys: Escape closes it (or clicks `closable` when it is a button name). Enter clicks its default
+//   button ("ok.default" in buttons), except in a textarea or an element contenteditable, where Enter is
+//   a new line and Ctrl+Enter (Cmd+Enter) clicks it. Out of a dialog, Enter goes to the next field,
+//   except in a textarea or a contenteditable.
 ```
 
 ### `MessageBox` / `InputBox` / `PromptBox` / `ProgressionBox`
@@ -1120,10 +1150,22 @@ class PromptBox extends Dialog {
 class ProgressionBox extends Dialog {
   constructor(title: string)
   addText(text: string|UnsafeHtml, perc: number): void
-  addError(text: string|UnsafeHtml, perc: number): void
-  clear(): void
-  done(): void                             // hide after 5s if no error, else show OK button
-}
+  addError(text: string|UnsafeHtml, perc: number): void     // its icon, in red; the title bar in red until clear()
+  addWarning(text: string|UnsafeHtml, perc: number): void   // its icon, in orange
+  addSection(title: string|UnsafeHtml, perc: number): void  // a section (<details>, open): the lines that follow go
+                                           // in it; a click on its title folds it; its title has the icon
+                                           // of the worst of its lines. Without any, the lines go in the log
+  setText(text: string|UnsafeHtml, perc: number): void      // in place of all the lines
+  clear(): void                            // no line, no error, no button OK
+  done(): void                             // shows OK: after an error or a warning it waits for a click,
+                                           // their counts on the left of the bar ("2 errors / 1 warning",
+                                           // from _tr.global.progression), the icon of the worst;
+                                           // else it counts "OK (5s)" and closes the box at 0
+}
+// ProgressionBox: its lines in a <pre>, 10 lines high, scrolled both ways (the box keeps its size);
+//   a string is text, an UnsafeHtml html. Ctrl+A in the lines selects them only (a folded section too).
+//   Colours: --msgbox-log-background, -border, -border-focus, -error-color, -warning-color,
+//   -scrollbar (the thumb of its scroll bars; their track is its background).
 ```
 
 ### `Notification`
@@ -1154,6 +1196,9 @@ class Form extends Box {
   validate(): FormValues                   // null if invalid; the values the validator changes are written back in their fields (any element with the name, every radio of a group)
 }
 // Collects all children (recursive) that have a "name" attribute and implement queryInterface("form-element").
+// Never sent by the browser: its "submit" is prevented (Enter in its only field would send it).
+// A Form is flex by default (it takes the free height of its box) and has a padding of 16px.
+//   flex: false: the height of its content (a toolbar, a line); its padding set back by a css rule.
 ```
 
 ---
@@ -1405,7 +1450,7 @@ class MyView extends VBox {
 }
 ```
 
-- A component shortcut also works while the focus is nowhere, if the component is the last one with shortcuts that had the focus: of two views shown together, the one the user works in answers.
+- A component shortcut also works while the focus is nowhere, if the component is the last one with shortcuts that had the focus: of two views shown together, the one the user works in answers. Not while that component is hidden (in a tab not shown, for instance).
 - A key typed in an `input`, a `textarea` or a `select` is not a shortcut, unless `editable` is set.
 - A key that what has the focus already used (it called `preventDefault` or `stopPropagation`) is not a shortcut.
 - A shortcut always takes its key (`preventDefault`). For a key that must sometimes be left alone, use a `keydown` handler instead.
@@ -1720,6 +1765,11 @@ createPainter(c2d: CanvasRenderingContext2D, w: number, h: number): CanvasEx   /
 initTooltips(): void                                   // initialize the global tooltip system
 ```
 
+No tooltip is shown until the application calls `initTooltips()` once (the prop `tooltip` only sets an attribute).
+`initTooltips()` shows the text of the attribute `tooltip` (the prop `tooltip`), or the one `getTip()`
+of a `"tip-handler"` gives, **as html**. A text that comes from a user is escaped by the application
+with `sanitizeHtml( text )`: `tooltip: \`Open <b>${sanitizeHtml( file.name )}</b>\``.
+
 ---
 
 ## State (`core_state`)

package/aiguide.md

@@ -20,7 +20,7 @@ Prefer:
 - plain objects for application data
 - `State` for observable application state
 - local events for things that happened locally
-- `GlobalEvent` for application-wide or distributed messages
+- a global message (`Application.fireGlobal`) for application-wide or distributed messages
 - `DataStore` for specialized tabular data
 - persistent `Component` objects backed by the real DOM
 - CSS and CSS variables for presentation and theming
@@ -84,13 +84,13 @@ For a simple event payload, `context` can carry the relevant identity or value w
 
 Do not put transient actions into State merely to trigger behavior.
 
-### GlobalEvent
+### Global messages
 
-Use `GlobalEvent` for application-wide messages.
+Use a global message (`Application.fireGlobal`) for application-wide messages.
 
-A GlobalEvent may also be transported between processes, clients or a server.
+A global message may also be transported between processes, clients or a server.
 
-Views should not care how a GlobalEvent is transported.
+Views should not care how a global message is transported.
 
 In particular, do not expose WebSocket details to UI components merely because WebSocket is used as the transport.
 
@@ -295,9 +295,24 @@ Do not use events as a replacement for persistent application state.
 
 ---
 
-## 9. GlobalEvent
+## 9. Global messages
 
-Use `GlobalEvent` for messages whose scope is the application or distributed system rather than a local component relationship.
+A global message is sent by `Application.fireGlobal( msg, params )` and received by
+`component.onGlobalEvent( ev => ... )`, `ev` an `EvMessage { msg, params }`. The listener of
+`onGlobalEvent` is taken off when the component leaves the page.
+
+```ts
+Application.fireGlobal( "device.updated", { id: deviceId } );
+
+this.onGlobalEvent( ( ev ) => {
+	if( ev.msg == "device.updated" ) {
+		this.refresh( ev.params.id );
+	}
+} );
+```
+
+Use a global message for what concerns the application or a distributed system, rather than a
+local component relationship.
 
 Global messages should normally use stable application-level names, for example:
 
@@ -318,11 +333,11 @@ The receiver can obtain the authoritative object through the application's model
 
 For high-frequency realtime information such as telemetry, carrying the actual data can be appropriate.
 
-Do not force every GlobalEvent into the same payload strategy.
+Do not force every global message into the same payload strategy.
 
 Most importantly:
 
-> GlobalEvent represents the message, not its transport.
+> A global message represents the message, not its transport.
 
 A view should normally not contain WebSocket-specific logic.
 
@@ -361,7 +376,7 @@ Model       obtains or modifies domain data
 State       represents current application state
 Component   presents that state
 Events      communicate local occurrences
-GlobalEvent communicates application-wide occurrences
+Global msg  communicates application-wide occurrences (Application.fireGlobal)
 ```
 
 Do not add additional layers unless they solve an actual problem.
@@ -500,11 +515,36 @@ Do not hide a control a component creates: configure the component through its p
 
 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 theme is a class on `<html>`. `Application.setTheme( name )` puts `x4theme-<name>` there and
+takes off the one before; `Application.setTheme( "" )` goes back to the light theme, the default;
+`Application.getTheme( )` gives the name. x4 has one theme: `"dark"`, like Dark Modern of VS Code.
+
+An application writes its own theme in its CSS, under `html.x4theme-<name>`, the way
+`themes.scss` writes the dark one:
+
+- the colour scale, `--color-primary-a0` (the background) to `--color-primary-a100` (the text).
+  The greys of x4 (backgrounds, texts, borders) are mixes of `a0` and `a100`: a scale whose
+  `a0` is dark and `a100` light gives them dark too;
+- the global variables the scale does not give, when the theme wants other values:
+  `--background-*`, `--text-*`, `--border*`, `--disabled-*`, `--accent-*`, `--icon-color*`,
+  `--alert-*`, `--warning-*`, `--success-*`;
+- `color-scheme: dark` for a dark theme: the native parts (select, scroll bars, spinners).
+
+The variables of a component (`--listbox-*`, `--dialog-*`…, listed in the `@cssvar` of its
+class) point to the global ones: the theme changes them all at once. Set one only when that
+component must differ from the rest; do not recolour components one by one.
+
+```css
+html.x4theme-pink {
+	--color-primary-a0: #fff5f8;
+	/* … a5 to a90 … */
+	--color-primary-a100: #3a1020;
+}
+```
 
-A dark theme gets its own scale.
+```ts
+Application.setTheme( "pink" );
+```
 
 ---
 
@@ -602,7 +642,7 @@ Component event
        ↓
 Application operation
        ↓
-State change / GlobalEvent
+State change / global message
        ↓
 Existing Components update
 ```
@@ -643,6 +683,15 @@ const app_fr = { app: { open: "Ouvrir", close: "Fermer" } };
 const app_en: typeof app_fr = { app: { open: "Open", close: "Close" } };
 ```
 
+`_tr` is typed with the texts of x4 only: `_tr.app.open` does not compile. Give the
+application its own typed view of `_tr`, once, from its first language:
+
+```ts
+export const tx = _tr as typeof _tr & typeof app_fr;
+
+new Button( { label: tx.app.open } );
+```
+
 ---
 
 ## Final rule

package/package.json

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

package/src/components/assets/icons.ts

@@ -19,6 +19,8 @@ const x4icons = {
 	danger: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor"><!--!Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zm0-384c13.3 0 24 10.7 24 24V264c0 13.3-10.7 24-24 24s-24-10.7-24-24V152c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"/></svg>`,
 	loading: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor"><!--!Font Awesome Pro 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2024 Fonticons, Inc.--><path d="M207.4 20.4c2.4 8.5-2.6 17.3-11.2 19.7C101.5 66.2 32 153 32 256c0 123.7 100.3 224 224 224s224-100.3 224-224c0-103-69.5-189.8-164.3-215.9c-8.5-2.4-13.5-11.2-11.2-19.7s11.2-13.5 19.7-11.2C432.5 39.1 512 138.2 512 256c0 141.4-114.6 256-256 256S0 397.4 0 256C0 138.2 79.5 39.1 187.7 9.2c8.5-2.4 17.3 2.6 19.7 11.2z"/></svg>`,
 	close_box: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512" fill="currentColor"><!--!Font Awesome Pro 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2024 Fonticons, Inc.--><path d="M192 233.4L59.5 100.9 36.9 123.5 169.4 256 36.9 388.5l22.6 22.6L192 278.6 324.5 411.1l22.6-22.6L214.6 256 347.1 123.5l-22.6-22.6L192 233.4z"/></svg>`,
+	// a triangle, a "!" cut in it
+	warning: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor"><path fill-rule="evenodd" d="M8 1L15.5 14.5H.5zM7.25 5.5h1.5V10h-1.5zM7 12a1 1 0 1 0 2 0a1 1 0 1 0-2 0z"/></svg>`,
 };
 
 export default x4icons;

package/src/components/button/button.ts

@@ -134,6 +134,11 @@ export class Button extends Component<ButtonProps,ButtonEvents> {
 	constructor( props: ButtonProps ) {
 		super( { ...props, tag: 'button', content: null } );
 
+		// a button, not a submit: in a <form>, Enter in a field would click the first submit
+		if( !props.attrs?.type ) {
+			this.setAttribute( "type", "button" );
+		}
+
 		this.mapPropEvents( props, 'click' );
 
 		if( props.autorepeat ) {

package/src/components/dialog/dialog.ts

@@ -125,6 +125,12 @@ export class Dialog<P extends DialogProps = DialogProps, E extends DialogEvents
 				}
 			}
 			else if (ev.key == 'Enter') {
+				// in a text of several lines Enter is a new line: Ctrl+Enter (Cmd+Enter) validates
+				const target = ev.target as HTMLElement;
+				if( ( target.tagName==="TEXTAREA" || target.isContentEditable ) && !ev.ctrlKey && !ev.metaKey ) {
+					return;
+				}
+
 				const def = this.query<Button>('button.default');
 				if (def) {
 					ev.preventDefault();

package/src/components/form/form.module.scss

@@ -31,8 +31,9 @@
         flex-direction: row;
     }
 
+	// flex: false: the height of its content (flex-grow alone would leave it at 0, flex-basis 0)
 	&.no-flex {
-		flex-grow: 0;
+		flex: none;
 	}
 }
 

package/src/components/form/form.ts

@@ -43,6 +43,9 @@ export class Form<P extends FormProps = FormProps> extends Box<P> {
 	constructor( props: P ) {
 		super( { tag: "form", ...props } );
 
+		// read by getValues, never sent by the browser (Enter in its only field would send it)
+		this.addDOMEvent( "submit", ( ev ) => ev.preventDefault( ) );
+
 		if( props.flex===false ) {
 			this.addClass( "no-flex" );
 		}

package/src/components/listbox/listbox.module.scss

@@ -34,6 +34,13 @@
 
 	--listbox-title-background: var( --background-primary );
 	--listbox-title-color: var( --text-primary );
+
+	--listbox-check-border: var( --border );
+	--listbox-check-border-hover: var( --border-hover );
+	--listbox-check-border-sel: var( --accent-color );
+	--listbox-check-background: var( --accent-background );
+	--listbox-check-background-disabled: var( --disabled-background );
+	--listbox-check-color: var( --accent-color );
 }
 
 .x4listbox {
@@ -50,6 +57,11 @@
         padding: 0 4px;
 	}
 
+	// the columns start after the case
+	&.checkable>.x4header {
+		padding-left: calc( 4px + 6px + 1rem );
+	}
+
 	&>.title {
 	    background: var( --listbox-title-background );
 		padding: 4px;
@@ -129,9 +141,49 @@
             }
         }
 
+        // checkable: the case at the start of the line
+        &>.x4check {
+            flex: none;
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            align-self: center;
+            vertical-align: middle;
+            box-sizing: border-box;
+            width: 1rem;
+            height: 1rem;
+            margin-left: 6px;
+            border: 1px solid var( --listbox-check-border );
+            color: var( --listbox-check-color );
+            cursor: pointer;
+
+            svg {
+                width: 70%;
+                height: 70%;
+                visibility: hidden;
+            }
+
+            &:hover {
+                border-color: var( --listbox-check-border-hover );
+            }
+        }
+
+        &.checked>.x4check {
+            background-color: var( --listbox-check-background );
+            border-color: var( --listbox-check-background );
+
+            svg {
+                visibility: visible;
+            }
+        }
+
+        &.selected>.x4check {
+            border-color: var( --listbox-check-border-sel );
+        }
+
         .column {
-            background-color: transparent; 
-            overflow: hidden; 
+            background-color: transparent;
+            overflow: hidden;
         }
 
         // 10 columns max (see Header)
@@ -232,6 +284,11 @@
 					&.selected {
 						background-color: var( --listbox-item-color-sel-disabled );
 					}
+
+					&.checked>.x4check {
+						background-color: var( --listbox-check-background-disabled );
+						border-color: var( --listbox-check-background-disabled );
+					}
 				}
 			}
 		}