x4js 2.3.24 → 2.3.26

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
 }
 
@@ -167,6 +169,15 @@ toggleClass(cls: string): void
 setClass(cls: string, set?: boolean): this
 ```
 
+A component gets one class for each class of its chain: its name in lower case, after the prefix that class
+declares itself with `static classPrefix` (not the one of its parent), then `x4`. Every component of x4 declares
+`static classPrefix = "x4"` (a Button: `x4button x4`); a class of the application declares its own, or none.
+
+```ts
+class Avatar extends Image { static classPrefix = "my"; }     // classes: myavatar x4image x4
+class Badge extends Label { }                                  // classes: badge x4label x4
+```
+
 ### HTML attributes & ARIA
 
 ```ts
@@ -220,7 +231,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
@@ -288,6 +300,11 @@ static fireGlobal(msg: string, params?: any): void
 static setTheme(name: string): void         // the class x4theme-<name> on <html>: "" the light theme (default, no class),
                                             // "dark" the dark theme of x4, another name a theme of the application
 static getTheme(): string                   // "" for the light theme, "dark", or the name given to setTheme
+static setLocale(locale: string, currency?: string): void   // forces the locale of the formats (formatNumber, formatMoney,
+                                            // formatDate, formatDateTime) over the one of the language; null: the language's
+                                            // again. currency: "EUR" by default, kept when not given
+static getLocale(): string                  // the forced one, else _tr.global.locale ("fr-FR" for fr, "en-US" for en)
+static getCurrency(): string
 focusNext(next: boolean): boolean
 addShortcut(keys: string | string[], callback: (ev: KeyboardEvent) => void, options?: ShortcutOptions): void   // see Shortcuts
 setupSocketMessaging(path?: string, looseCallback?: () => void): void
@@ -310,8 +327,14 @@ class VBox<P, E> extends Box<P, E>
 interface BoxProps extends ComponentProps { tag?: string }
 ```
 
+A Box is a `<div>` (another element with `tag`). Disabled (`disable()`, the prop `disabled`), its content is inert
+(no click, no focus, no input) and faded by `--box-disabled-opacity` (0.5); a disabled Box in it is not faded twice.
+
 ### `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 +849,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 +1076,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 +1119,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 +1144,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 +1167,24 @@ 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     // red, on a light red line, a red bar on its left;
+                                                            // the title bar in red until clear()
+  addWarning(text: string|UnsafeHtml, perc: number): void   // the same 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> in a fixed font, a <div> each (class "line", plus "error" or "warning"),
+//   10 lines high, scrolled both ways (the box keeps its size), every line as wide as the longest one;
+//   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, -error-background,
+//   -warning-color, -warning-background, -scrollbar (the thumb of its scroll bars; their track is its background).
 ```
 
 ### `Notification`
@@ -1146,7 +1207,8 @@ class Notification extends Popup { display(time_in_s?: number): void }   // 0: u
 ```ts
 type FormValues = Record<string, any>
 interface FormProps extends BoxProps { autoComplete?: boolean }
-class Form extends Box {
+class Form<P extends FormProps = FormProps, E extends ComponentEvents = ComponentEvents> extends Box<P, E> {
+  // a class derived from Form declares its events: class EntryForm extends Form<EntryProps, EntryEvents>
   setValues(values: FormValues): void
   getValues<T extends FormValues>(): T
   setAutoComplete(on?: boolean): void      // attribute on the <form>: fields without their own follow it, added later too
@@ -1154,6 +1216,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.
 ```
 
 ---
@@ -1240,9 +1305,11 @@ class VSplitBox extends VBox               // panels stacked, resizable height:
 // 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 CSizer extends Component             // base splitter; events start, resize { size, width, height }, stop
 class HSizer extends CSizer                // horizontal splitter
 class VSizer extends CSizer                // vertical splitter
+// A pointercancel (a touch taken by the browser) ends the resize as a pointerup does: stop is fired.
+// The columns of a Gridview or a Spreadsheet are 16px wide at least (the min-width of a cell).
 class ScrollView extends Component { getViewport(): Component }
 class Viewport extends Component
 class Canvas extends Component { getContext(): CanvasRenderingContext2D; paint(): void }
@@ -1405,7 +1472,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.
@@ -1507,10 +1574,18 @@ isLanguage(name: string): boolean
 //   search search_tip required_field invalid_format invalid_email invalid_number invalid_date
 //   empty_list err_403 property value copy cut paste filedrop
 //   diff_date_seconds/minutes/hours, date_input_formats, date_format, date_time_format,
+//   locale ("fr-FR", "en-US", "es-ES", "de-DE": the formats of numbers, amounts, dates),
 //   day_short[] day_long[] month_short[] month_long[], keyboard.{next,numeric,alpha},
-//   settings.{search,nomatch}
+//   settings.{search,nomatch}, progression.{error,errors,warning,warnings}
+getCurrentLocale(): string; getCurrentCurrency(): string   // as Application.getLocale / getCurrency
 ```
 
+The language gives the texts and the locale of the formats: `selectLanguage("en")` changes both. A regional
+variant is a language based on another: `createLanguage("fr-ch", "fr")`, `addTranslation("fr-ch", { global: { locale: "fr-CH" } })`.
+`Application.setLocale(locale, currency)` forces the locale over the language's. The fields of date and the
+Calendar follow the patterns of the language (`date_format`...), not the locale. A field of type number is shown
+by the browser, in its own locale, whatever this one.
+
 ---
 
 ## Theme (`themes.scss`)
@@ -1584,7 +1659,14 @@ pascalCase(s): string; camelCase(s): string; clamp<T>(v, min, max): T
 measureText(str, size, bold?): number      // width in Helvetica, from core_pdf (see PDF)
 
 // Dates
-date_format(date, options?): string       // options not read yet: formatIntlDate(date)
+date_format(date, options?): string       // options: Intl.DateTimeFormat in the locale; without: formatIntlDate(date)
+
+// Formats in the current locale (Application.setLocale, else the one of the language), Intl made once by locale
+formatNumber(value, decimals?, grouping = true): string   // "1 234,5" in fr-FR; decimals: the most shown
+formatMoney(value): string                 // "1 234,50 €": the currency of Application.getCurrency()
+formatDate(date): string                   // "22/10/2026"
+formatDateTime(date): string               // "22/10/2026 14:05"
+// Gridview and Spreadsheet format their columns number, money, date, date-time with them (a formatter comes first)
 date_diff(date1, date2, options?): string   // "30 secondes", "5 minutes", "2 heures 5 minutes" (either order); options not read
 date_to_sql(date, withHours): string; date_sql_utc(date): Date
 date_hash(date): number; date_clone(date): Date
@@ -1603,9 +1685,6 @@ getSystemMetrics(part: "scrollbar"|"zoom"): number
 setWaitCursor(wait: boolean): void; beep(): void
 isUnitLess(name): boolean; isFeatureAvailable(name: "eyedropper"): boolean
 
-// Class decorator
-class_ns(ns: string): ClassDecorator
-const x4_class_ns_sym: symbol
 const unitless                              // set of unitless CSS props
 
 // System interfaces
@@ -1720,6 +1799,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.26",
   "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/autocomplete/autocomplete.ts

@@ -16,7 +16,7 @@
 
 import { Component, ComponentEvent, ComponentEvents, EvChange } from '../../core/component';
 import { EventCallback } from '../../core/core_events';
-import { class_ns, kbNav } from '../../core/core_tools';
+import { kbNav } from '../../core/core_tools';
 
 import { HBox } from '../boxes/boxes';
 import { DropdownList } from '../combobox/combobox';
@@ -96,8 +96,8 @@ const render_id_item = ( item: ListItem ) => {
  * })
  */
 
-@class_ns( "x4" )
 export class AutoComplete extends TextEdit<AutoCompleteEvents> {
+	static classPrefix = "x4";
 
 	private _popup: DropdownList;
 

package/src/components/boxes/boxes.module.scss

@@ -16,16 +16,30 @@
 
 @use "../shared.scss";
 
+:root {
+	--box-disabled-opacity: 0.5;		// a disabled Box: its content faded
+}
+
 .x4box {
-	// reset fieldset
+	// reset a box built with tag: "fieldset"
 	margin: 0;
-	padding: 0;	
+	padding: 0;
 	border: none;
 
 	min-width: 0;
 	min-height: 0;
 	flex-shrink: 0;
 	align-self: stretch;
+
+	// disabled: its content inert (enable) and faded
+	&[disabled] {
+		opacity: var( --box-disabled-opacity );
+
+		// a disabled Box in a disabled Box: opacity 1 for it, so faded once, not twice
+		.x4box[disabled] {
+			opacity: 1;
+		}
+	}
 }
 
 .x4hbox {

package/src/components/boxes/boxes.ts

@@ -14,7 +14,7 @@
  * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
  **/
 
-import { asap, class_ns, isArray, isNumber } from '../../core/core_tools';
+import { asap, 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';
@@ -28,6 +28,14 @@ export interface BoxProps extends ComponentProps {
 
 /**
 * A generic container component for grouping and laying out child components.
+ *
+ * A <div>. Disabled (disable( ), the prop disabled), its content is inert (no click, no
+ * focus, no input) and faded by --box-disabled-opacity.
+ *
+ * @cssvar
+ * ```
+ * --box-disabled-opacity
+ * ```
  *
  * The `refs` object is a typed directory of the children you need to reach
  * again later. Assign a child to `refs` as you build the content: the
@@ -60,11 +68,12 @@ export interface BoxProps extends ComponentProps {
  * 
  */
 
-@class_ns( "x4" )
 export class Box<P extends BoxProps=BoxProps,E extends ComponentEvents=ComponentEvents> extends Component<P,E> {
+	static classPrefix = "x4";
+
 	protected refs: Record<string,Component> = {};
 	constructor( props: P ) {
-		super( { tag: "fieldset", ...props } );
+		super( { tag: "div", ...props } );
 	}
 }
 
@@ -74,8 +83,9 @@ export class Box<P extends BoxProps=BoxProps,E extends ComponentEvents=Component
  * Arranges child components in a horizontal line.
  */
 
-@class_ns( "x4" )
 export class HBox<P extends BoxProps=BoxProps,E extends ComponentEvents=ComponentEvents> extends Box<P,E> {
+	static classPrefix = "x4";
+
 }
 
 /**
@@ -84,8 +94,9 @@ export class HBox<P extends BoxProps=BoxProps,E extends ComponentEvents=Componen
  * The CSS class for this component is automatically generated as `x4vbox`.
  */
 
-@class_ns( "x4" )
 export class VBox<P extends BoxProps=BoxProps,E extends ComponentEvents=ComponentEvents> extends Box<P,E> {
+	static classPrefix = "x4";
+
 	constructor( p: P ) {
 		super( p );
 	}
@@ -136,8 +147,9 @@ function split_content( panels: Component[], horz: boolean ) {
  * })
  */
 
-@class_ns( "x4" )
 export class HSplitBox<P extends SplitBoxProps=SplitBoxProps,E extends ComponentEvents=ComponentEvents> extends HBox<P,E> {
+	static classPrefix = "x4";
+
 	constructor( props: P ) {
 		super( { ...props, content: split_content( props.content, true ) } );
 	}
@@ -149,8 +161,9 @@ export class HSplitBox<P extends SplitBoxProps=SplitBoxProps,E extends Component
  * 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> {
+	static classPrefix = "x4";
+
 	constructor( props: P ) {
 		super( { ...props, content: split_content( props.content, false ) } );
 	}
@@ -206,8 +219,8 @@ interface StackItemEx extends StackItem {
  * The CSS class for this component is automatically generated as `x4stackbox`.
  */
 
-@class_ns( "x4" )
 export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeBoxEvents = StackeBoxEvents>  extends Box<StackBoxProps,StackeBoxEvents> {
+	static classPrefix = "x4";
 	
 	protected _items: StackItemEx[];
 	protected _cur: number;
@@ -371,8 +384,8 @@ export class StackBox<P extends StackBoxProps = StackBoxProps, E extends StackeB
  * The CSS class for this component is automatically generated as `x4assistbox`.
  */
 
-@class_ns( "x4" )
 export class AssistBox extends StackBox {
+	static classPrefix = "x4";
 
 	/**
      * Selects the next or previous page in the stack.
@@ -433,8 +446,8 @@ export interface GridBoxProps extends Omit<BoxProps,"content"> {
  * Auto-generates CSS class: `x4gridbox`.
  */
 
-@class_ns("x4")
 export class GridBox<P extends GridBoxProps=GridBoxProps,E extends ComponentEvents=ComponentEvents> extends Box<P,E> {
+	static classPrefix = "x4";
 
 	constructor( props: P ) {
 		super( props );
@@ -543,8 +556,8 @@ interface MasonryProps extends Omit<BoxProps,"content"> {
  * Auto-generates CSS class: `x4masonrybox`.
  */
 
-@class_ns("x4")
 export class MasonryBox extends Box<MasonryProps> {
+	static classPrefix = "x4";
 
 	constructor(props: MasonryProps ) {
 		super(props);

package/src/components/breadcrumb/breadcrumb.ts

@@ -14,7 +14,6 @@
  * that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
  **/
 
-import { class_ns } from '../../core/core_tools';
 import { parseRoute, Router } from '../../core/core_router';
 
 import { BoxProps, Button, HBox, Icon } from '../components';
@@ -64,8 +63,8 @@ interface BreadcrumbsProps extends BoxProps{
  * ```
  */
 
-@class_ns( "x4" )
 export class Breadcrumbs extends HBox<BreadcrumbsProps,BreadcrumbEvents> {
+	static classPrefix = "x4";
 
 	constructor( props: BreadcrumbsProps ) {
 		super( props );

package/src/components/btngroup/btngroup.ts

@@ -16,7 +16,7 @@
 
 import { Component, ComponentEvents, ComponentProps, Flex, Space } from '../../core/component';
 import { EventCallback } from '../../core/core_events';
-import { class_ns, isString } from '../../core/core_tools';
+import { isString } from '../../core/core_tools';
 import { _tr } from '../../core/core_i18n'
 
 import { Button } from '../button/button';
@@ -64,8 +64,8 @@ interface BtnGroupProps extends Omit<ComponentProps,"content"> {
  * a packed group draws its buttons with the --ol-button-* variables of Button
  */
 
-@class_ns( "x4" )
 export class BtnGroup extends Box<BtnGroupProps,BtnGroupEvents> {
+	static classPrefix = "x4";
 
 	constructor( props: BtnGroupProps ) {
 		super( props );