x4js 2.3.15 → 2.3.17

package/aicontext.md

@@ -39,7 +39,7 @@ CoreElement<E>                 named timers + event surface (no DOM)
   │     ├── Progress, TickLine, Canvas, Image, Spreadsheet, MonacoEditor
   │     ├── SvgComponent → Chart
   │     ├── CSizer → HSizer / VSizer
-  │     ├── FileDialog, ScrollView, Viewport, Flex, Space
+  │     ├── FileDialog, ScrollView, Viewport, DockingView, Flex, Space
   │     ├── HBox-based: ColorInput, Rating, Switch, Keyboard, TextEdit → AutoComplete, Breadcrumbs
   │     └── VBox-based: Calendar, ColorPicker, FileDrop, Panel, PropertyGrid, TextArea
   └── Application<E>           singleton, no DOM of its own
@@ -50,7 +50,7 @@ EventSource<E>                 standalone event registry
   └── StateManager<T>
 
 CoreElement-based (non-DOM): DataProxy, DataView, Store
-Standalone: Rect, Timer, Color, DataModel, Stylesheet, ComputedStyle,
+Standalone: Rect, Timer, Color, DataModel, Shortcuts, Stylesheet, ComputedStyle,
             SvgBuilder, X4PDFBuilder, x4_react, CMover, UnsafeHtml (extends String)
 ```
 
@@ -240,6 +240,7 @@ setCapture(pointerId: number): void;  releaseCapture(pointerId: number): void
 animate(keyframes: Keyframe[], duration: number): void
 onGlobalEvent(cb: (ev: EvMessage) => void): void   // auto-removed on DOM removal
 queryInterface<T>(name: string): T     // "form-element" → IFormElement; "tab-handler" → ITabHandler
+addShortcut(keys: string | string[], callback: (ev: KeyboardEvent) => void, options?: ShortcutOptions): this   // see Shortcuts
 ```
 
 ### Exported helpers
@@ -264,7 +265,7 @@ interface EvDblClick extends ComponentEvent {}
 interface EvBtnClick extends CoreEvent { button: string }
 
 // Spacers
-class Flex extends Component    // CSS "x4flex"
+class Flex extends Component    // new Flex(), no argument; CSS "x4flex"
 class Space extends Component   // new Space(width?: number|string, cls?: string)
 ```
 
@@ -285,6 +286,7 @@ setEnv(name: string, value: any): void
 getEnv(name: string, def_value?: any): any
 static fireGlobal(msg: string, params?: any): void
 focusNext(next: boolean): boolean
+addShortcut(keys: string | string[], callback: (ev: KeyboardEvent) => void, options?: ShortcutOptions): void   // see Shortcuts
 setupSocketMessaging(path?: string, looseCallback?: () => void): void
 getStorage(name: string): string
 setStorage(name: string, value: string|number): void
@@ -387,6 +389,84 @@ class MasonryBox extends Box {
 
 ---
 
+## `DockingView` — panels the user arranges by dragging their title
+
+Not a `Box`. Two kinds of panels, which never mix: **tools**, docked in a band on the left or on the right
+(one above the other, side by side, or as tabs) and which can float; **contents**, what is worked on
+(as the editors of an IDE), which share the room between the bands, split or as tabs.
+
+```ts
+interface DockPanel {
+  id: string
+  title?: string                           // shown in its tab; the id when missing
+  content: Component
+  kind?: 'tool' | 'content'                // default 'tool'
+  closable?: boolean                       // for this panel, instead of the view's
+  floating?: boolean                       // idem; a content never floats
+  sides?: DockSide[]                       // a tool: the bands it may be docked in, instead of the view's
+}
+interface DockingViewProps extends ComponentProps {
+  panels: DockPanel[]
+  layout: DockLayout                       // where the panels are at first
+  floating?: boolean                       // tools can float above the rest
+  closable?: boolean                       // tools have a button that hides them
+  sides?: DockSide[]                       // the bands tools may be docked in; left and right when missing
+  persist?: string                         // a name: the layout is remembered under it (application storage)
+  layoutChange?: EventCallback<ComponentEvent>
+}
+class DockingView extends Component {
+  getState(): DockLayout                   // plain data, to save
+  setState(layout: unknown): void          // a saved layout; what it lacks comes from props.layout
+  resetLayout(): void                      // back to props.layout
+  showPanel(id: string, show?: boolean): void
+  isPanelVisible(id: string): boolean
+}
+
+interface DockLayout {
+  left: DockBand; right: DockBand          // the tools, on the sides
+  top?: DockBand; bottom?: DockBand        // the tools above and under the contents, between left and right
+  content: DockNode                        // the contents; null when there is none
+  floats: DockFloat[]                      // floating tools: { panel, x, y, w, h }
+  hidden: string[]                         // ids of the closed panels
+}
+interface DockBand { size: number; root: DockNode }            // size: width in px (height for top/bottom); root: null when empty
+type DockSide = 'left' | 'right' | 'top' | 'bottom'
+type DockNode  = DockStack | DockSplit
+interface DockStack { type: 'stack'; size: number; panels: string[]; active: string }    // one tab per panel
+interface DockSplit { type: 'split'; dir: 'row' | 'column'; size: number; children: DockNode[] }
+// size of a node: its share of its split (0 = an equal share)
+```
+
+```ts
+const view = new DockingView({
+  flex: true,
+  floating: true,
+  closable: true,
+  persist: 'myapp.layout',
+  panels: [
+    { id: 'tools', title: 'Tools', content: tools },
+    { id: 'props', title: 'Properties', content: props },
+    { id: 'page', kind: 'content', content: editor },
+  ],
+  layout: {
+    left:  { size: 180, root: { type: 'stack', size: 0, panels: ['tools'], active: 'tools' } },
+    right: { size: 260, root: { type: 'stack', size: 0, panels: ['props'], active: 'props' } },
+    content: { type: 'stack', size: 0, panels: ['page'], active: 'page' },
+    floats: [],
+    hidden: [],
+  },
+})
+```
+
+- A closed panel is hidden, not removed: `showPanel(id)` brings it back where it was. Offer it in a menu.
+- Tools only go in the bands or in `floats`; contents only in `content`. A panel missing from the layout is added where its kind goes.
+- A tool goes in `left` or `right` only, unless `sides` says otherwise (on the view, or on one panel): `sides: ['bottom']` for what is wide and low (a log, a list of results). It is never offered a place in a band it may not be in.
+- A content alone has no title bar; with several contents, each stack has tabs.
+- What a panel shows is built once (`content`) and moved as the layout changes: never rebuild it.
+- CSS variables: `--dock-line`, `--dock-accent`, `--dock-title-background`, `--dock-title-background-hover`, `--dock-title-color`, `--dock-title-color-active`, `--dock-float-background`, `--dock-float-shadow`.
+
+---
+
 ## Display components
 
 ### `Label`
@@ -460,14 +540,15 @@ class Image extends Component {
 ### `Progress`
 
 ```ts
-interface ProgressProps extends ComponentProps { /* min/max/value */ }
+interface ProgressProps extends ComponentProps { value: number; min?: number /* 0 */; max?: number /* 100 */ }
+// the bar is where value is between min (0%) and max (100%)
 class Progress extends Component { setValue(value: number): void }
 ```
 
 ### `Gauge`
 
 ```ts
-interface GaugeProps extends ComponentProps { min?: number; max?: number; colors?: string[] }
+interface GaugeProps extends ComponentProps { min?: number /* 0 */; max?: number /* 100 */; colors?: string[] }
 class Gauge extends Component {
   setRange(min: number, max: number): void
   setPos(pos: number): void
@@ -541,6 +622,11 @@ class TextEdit extends HBox {
 ### `TextArea`
 
 ```ts
+interface TextAreaProps extends BaseProps {      // BaseProps: see Input (name, readonly, placeholder...)
+  label?: string; value?: string
+  resize?: boolean | "none" | "vertical" | "horizontal" | "both"
+  trim?: boolean                           // getText() trims, unless false
+}
 class TextArea extends VBox { getText(): string; setText(text: string): void }
 ```
 
@@ -561,7 +647,13 @@ class Checkbox extends Component {
 ### `Radio`
 
 ```ts
-interface RadioProps extends ComponentProps { /* label, value, name, group */ }
+interface RadioProps extends ComponentProps {
+  label: string; icon?: string
+  name: string                             // required: the radios that have the same name are one group
+  value: number | string                   // required
+  checked?: boolean
+  change?: EventCallback<EvChange>
+}
 class Radio extends Component {
   getValue(): string; setCheck(ck: boolean): void
   setLabel(text: string): void
@@ -572,14 +664,19 @@ class Radio extends Component {
 ### `Switch`
 
 ```ts
-interface SwitchProps extends ComponentProps { /* label, checked, name */ }
+interface SwitchProps extends ComponentProps { label: string; checked?: boolean; name?: string }
+// with a name, a Form reads and writes it as a boolean
 class Switch extends HBox {}
 ```
 
 ### `Slider`
 
 ```ts
-interface SliderProps extends ComponentProps { /* min, max, value, step */ }
+interface SliderProps extends ComponentProps {
+  value: number; min: number; max: number  // required
+  step?: number; vertical?: boolean
+  change?: EventCallback<EvChange>
+}
 class Slider extends Component {
   setMin(min: number): void; setMax(max: number): void; setValue(v: number): void
 }
@@ -590,17 +687,29 @@ class Slider extends Component {
 ```ts
 interface SelectProps extends ComponentProps {
   items: ListItem[]                        // required
-  value: string                            // required
-  multiple?: boolean; name?: string
+  value?: ListboxID                        // the id of the item that is selected
+  multiple?: boolean; required?: boolean; name?: string
   change?: EventCallback<EvChange>; focus?: EventCallback<EvFocus>
 }
-class Select extends Component { getValue(): string; setValue(value: string): void; setItems(items: ListItem[]): void }
+class Select extends Component {
+  getValue(): ListboxID; setValue(value: ListboxID): void
+  getSelValues(): ListboxID[]; setSelValues(values: ListboxID[]): void   // multiple
+  setItems(items: ListItem[]): void
+}
 ```
 
 ### `Combobox` — input + dropdown list
 
 ```ts
-interface ComboboxProps extends ComponentProps { /* items, value, renderer... */ }
+interface ComboboxProps extends ComponentProps {
+  items: ListItem[]                        // required
+  value?: ListboxID                        // the id of the item that is selected
+  label?: string; labelWidth?: number | string
+  readonly?: boolean                       // true by default: the user picks, and cannot type. false to let him type
+  renderer?: (item: ListItem) => Component // draws an item of the list (the field still shows item.text)
+  required?: boolean; name?: string
+  selectionChange?: EventCallback<EvSelectionChange>
+}
 class Combobox extends Component {
   getValue(): string; setValue(value: string): void
   getInput(): Input
@@ -950,7 +1059,14 @@ class ProgressionBox extends Dialog {
 ### `Notification`
 
 ```ts
-class Notification extends Popup { display(time_in_s?: number): void }
+interface NotificationProps extends ComponentProps {
+  title: string; text: string | UnsafeHtml
+  mode?: "success" | "danger"
+  loading?: boolean                        // a turning icon
+  iconId?: string
+  closable?: boolean                       // a button that closes it
+}
+class Notification extends Popup { display(time_in_s?: number): void }   // 0: until it is closed
 ```
 
 ---
@@ -1100,6 +1216,46 @@ parseRoute(str: string|RegExp, loose?: boolean): Segment
 
 ---
 
+## Shortcuts (`core_shortcuts`)
+
+Keyboard shortcuts. A sequence is written as it is read: `"Mod+C"`, `"Shift+Mod+Z"`, `"Delete"`, `"Alt+ArrowLeft"`.
+Modifiers: `Shift`, `Ctrl`, `Cmd`, `Alt`, and `Mod` = the key of the commands (Ctrl on Windows and Linux, Cmd on a Mac). Prefer `Mod`.
+
+```ts
+interface ShortcutOptions { editable?: boolean }       // true: also while the user types in a field
+
+component.addShortcut(keys, callback, options?)         // a view: while the focus is in the component
+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
+
+class Shortcuts {                                       // the list itself; rarely used directly
+  add(keys: string | string[], callback: (ev: KeyboardEvent) => void, options?: ShortcutOptions): void
+  clear(): void
+  handle(ev: KeyboardEvent): boolean                   // true when the key was a shortcut
+}
+```
+
+```ts
+class MyView extends VBox {
+  constructor(props: BoxProps) {
+    super(props)
+    this.addShortcut('Mod+C', () => this.copy())
+    this.addShortcut(['Mod+Y', 'Shift+Mod+Z'], () => this.redo())
+    this.setContent(new Button({ label: 'Undo', tooltip: shortcutText('Mod+Z'), click: () => this.undo() }))
+  }
+}
+```
+
+- 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 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.
+- An application shortcut also works while a dialog is open.
+- Do not write a `keydown` handler with a `switch` on `ev.ctrlKey` for commands: use `addShortcut`.
+
+---
+
 ## i18n (`core_i18n`)
 
 Two built-in languages (`fr` default, and `en`).
@@ -1499,6 +1655,7 @@ Optional keys: `external`, `define`, `esbuild`, `dev` (`host`, `port`, `https`,
 - `Component` stores its instance on its DOM node. Use `componentFromDOM(el)` to retrieve a component from an `HTMLElement`.
 - Numbers passed to `setStyle`/`setStyleValue` are auto-suffixed with `"px"` except for unitless properties (see the `unitless` set: `zIndex`, `opacity`, `flexGrow`...).
 - `show(false)` / `hide()` toggle the `"x4hidden"` CSS class, not `display:none`.
+- x4 sets `user-select: none` on every element (`*`): text that must be selectable needs `user-select: text` on it and on its descendants.
 - `enable(false)` / `disable()` propagate the `disabled` state to child `<input>` and `<button>` elements.
 - `Application` is a strict singleton — one instance per page (an assertion fails otherwise).
 - `Popup.show()` routes to `displayCenter()`. To position, call `displayAt()` or `displayNear()` instead.

package/package.json

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

package/src/components/colorinput/colorinput.module.scss

@@ -50,10 +50,10 @@
 			}
 		}
 
-		// props.nullable, no color: crossed out
+		// props.nullable, no color: the checkerboard that stands for what is transparent
 		&.none {
 			border: 1px solid var( --border );
-			background: linear-gradient( to top right, transparent 45%, #d04040 45%, #d04040 55%, transparent 55% );
+			background: repeating-conic-gradient( #c8c8c8 0% 25%, #ffffff 0% 50% ) 0 0 / 6px 6px;
 		}
 	}
 

package/src/components/colorpicker/colorpicker.module.scss

@@ -147,9 +147,9 @@
 				border-color: var( --border-focus );
 			}
 
-			// no color: crossed out
+			// no color: the checkerboard that stands for what is transparent
 			&.none {
-				background: linear-gradient( to top right, transparent 45%, #d04040 45%, #d04040 55%, transparent 55% );
+				background: repeating-conic-gradient( #c8c8c8 0% 25%, #ffffff 0% 50% ) 0 0 / 6px 6px;
 			}
 		}
 	}

package/src/components/combobox/combobox.ts

@@ -87,6 +87,10 @@ interface ComboboxProps extends Omit<ComponentProps,"content"> {
 	readonly?: boolean;
 	required?: boolean;
 	items: ListItem[];
+
+	/** draws an item of the list, instead of its text. The field still shows the text of the item that is chosen. */
+	renderer?: ( item: ListItem ) => Component;
+
 	selectionChange?: EventCallback<EvSelectionChange>,
 }
 
@@ -139,7 +143,7 @@ export class Combobox extends Component<ComboboxProps,ComboboxEvents> {
 			this.setAttribute( "required", true );
 		}
 
-		this._popup = new DropdownList( { items: props.items } );
+		this._popup = new DropdownList( { items: props.items, renderer: props.renderer } );
 		const list = this._popup.getList( );
 
 		const _select = ( sel: ListboxID ) => {

package/src/components/components.ts

@@ -12,6 +12,7 @@ export * from "./colorinput/colorinput"
 export * from "./colorpicker/colorpicker"
 export * from "./combobox/combobox"
 export * from "./dialog/dialog"
+export * from "./dockingview/dockingview"
 export * from "./filedrop/filedrop"
 export * from "./form/form"
 export * from "./gauge/gauge"

package/src/components/dockingview/dockingview.module.scss

@@ -0,0 +1,297 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file dockingview.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.
+ **/
+
+.x4dockingview {
+	--dock-line: var( --border, #cfdae0 );						// between two panels, under a title
+	--dock-title-background: var( --background-secondary, #f3f7f9 );
+	--dock-title-background-hover: color-mix( in srgb, var( --dock-accent ) 25%, transparent );
+	--dock-title-color: var( --text-ternary, #607784 );
+	--dock-title-color-active: var( --text-primary, #002a40 );
+	--dock-accent: var( --accent-background, #126e9e );			// the tab in front, the sizer under the pointer, the preview
+	--dock-float-background: var( --background-primary, white );
+	--dock-float-shadow: 0 6px 24px rgba( 0, 0, 0, 0.35 );
+
+	position: relative;
+	display: flex;
+	min-width: 0;
+	min-height: 0;
+	overflow: hidden;
+
+	// it has no size of its own: it takes what its container gives it,
+	// even in an HBox, which centers its children
+	align-self: stretch;
+
+	// The boxes of the layout: the band of the left, what is between the
+	// two, the band of the right. The floating tools are placed from its
+	// top-left corner, which is the one of the box.
+	> .dock-frame {
+		position: relative;
+		display: flex;
+		flex: 1 1 0;
+		min-width: 0;
+		min-height: 0;
+	}
+
+	// Between the bands of the left and of the right, one above the other:
+	// the band of the top, the room of the contents, the band of the bottom.
+	.dock-middle {
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 0;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+	}
+
+	// The tools of one side. Its width is given by the layout; it only
+	// gets narrower when the box has no room left.
+	.dock-band {
+		display: flex;
+		flex: 0 1 auto;
+		min-width: 48px;
+		min-height: 0;
+		overflow: hidden;
+
+		> .dock-split,
+		> .dock-stack {
+			flex: 1 1 0;
+		}
+
+		// the bands that lie flat: it is their height that the layout gives
+		&.top,
+		&.bottom {
+			min-width: 0;
+			min-height: 48px;
+		}
+	}
+
+	// the room of the contents: what the bands leave
+	.dock-area {
+		display: flex;
+		flex: 1 1 0;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+
+		> .dock-split,
+		> .dock-stack {
+			flex: 1 1 0;
+		}
+	}
+
+	.dock-split {
+		display: flex;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+
+		&.column {
+			flex-direction: column;
+		}
+
+		// the smallest size of a child (MIN_SIZE in dockingview.ts)
+		&.row > .dock-split,
+		&.row > .dock-stack {
+			min-width: 48px;
+		}
+
+		&.column > .dock-split,
+		&.column > .dock-stack {
+			min-height: 48px;
+		}
+	}
+
+	// One line between two children. It is caught from a little further
+	// than what is drawn.
+	.dock-sizer {
+		position: relative;
+		z-index: 1;
+		flex: none;
+		align-self: stretch;
+		min-width: 1px;
+		min-height: 1px;
+		background: var( --dock-line );
+		touch-action: none;
+
+		&::after {
+			content: "";
+			position: absolute;
+		}
+
+		&:hover,
+		&:active {
+			background: var( --dock-accent );
+		}
+	}
+
+	// between two boxes that are side by side
+	.dock-sizer.row {
+		cursor: ew-resize;
+
+		&::after {
+			inset: 0 -3px;
+		}
+	}
+
+	// between two boxes that are one above the other
+	.dock-sizer.column {
+		cursor: ns-resize;
+
+		&::after {
+			inset: -3px 0;
+		}
+	}
+
+	.dock-stack {
+		display: flex;
+		flex-direction: column;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+
+		// what a panel shows keeps its z-index for itself: it stays under
+		// the floating panels
+		isolation: isolate;
+	}
+
+	// the titles of a stack, which are also what it is dragged by
+	.dock-titles {
+		display: flex;
+		flex: none;
+		overflow: hidden;
+		background: var( --dock-title-background );
+		border-bottom: 1px solid var( --dock-line );
+		cursor: grab;
+		user-select: none;
+		touch-action: none;
+	}
+
+	.dock-title {
+		display: flex;
+		flex: none;
+		align-items: center;
+		gap: 6px;
+		padding: 6px 8px;
+		font-weight: 600;
+		white-space: nowrap;
+		color: var( --dock-title-color );
+
+		// under the pointer: it can be taken
+		&:hover {
+			color: var( --dock-title-color-active );
+			background: var( --dock-title-background-hover );
+		}
+
+		// The only title of a stack takes the whole bar: its button is at
+		// the end of it. Among several tabs, it follows the text of its tab.
+		&:only-child {
+			flex: 1 1 0;
+			min-width: 0;
+
+			> span {
+				flex: 1 1 0;
+				min-width: 0;
+				overflow: hidden;
+				text-overflow: ellipsis;
+			}
+		}
+
+		// several tabs: the one in front stands out
+		&.active:not( :only-child ) {
+			color: var( --dock-title-color-active );
+			box-shadow: inset 0 -2px 0 var( --dock-accent );
+		}
+	}
+
+	.dock-close {
+		width: 16px;
+		height: 16px;
+		line-height: 16px;
+		border-radius: 3px;
+		text-align: center;
+		font-weight: 400;
+		cursor: pointer;
+		opacity: 0.6;
+
+		&:hover {
+			opacity: 1;
+			background: var( --dock-line );
+		}
+	}
+
+	.dock-body {
+		display: flex;
+		flex: 1 1 0;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+	}
+
+	// what a panel shows fills its page
+	.dock-page {
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 0;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+
+		> * {
+			flex: 1 1 0;
+			min-width: 0;
+			min-height: 0;
+		}
+	}
+
+	.dock-float {
+		position: absolute;
+		z-index: 20;
+		display: flex;
+		flex-direction: column;
+		min-width: 120px;
+		min-height: 80px;
+		overflow: hidden;
+		isolation: isolate;
+
+		background: var( --dock-float-background );
+		border: 1px solid var( --dock-line );
+		border-radius: 4px;
+		box-shadow: var( --dock-float-shadow );
+	}
+
+	// where the panel that is dragged will go
+	.dock-preview {
+		position: absolute;
+		z-index: 30;
+		box-sizing: border-box;
+		pointer-events: none;
+
+		background: color-mix( in srgb, var( --dock-accent ) 30%, transparent );
+		border: 1px solid var( --dock-accent );
+		border-radius: 3px;
+	}
+
+	// It holds the pointer during a drag: its cursor is the one that shows.
+	// It must be in the page to do so, but takes no room.
+	.dock-grip {
+		position: absolute;
+		left: 0;
+		top: 0;
+		width: 0;
+		height: 0;
+		cursor: grabbing;
+	}
+}