x4js 2.3.14 → 2.3.16

package/aicontext.md

@@ -39,17 +39,18 @@ 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
 
 EventSource<E>                 standalone event registry
   ├── DataStore<T>
-  └── Router
+  ├── Router
+  └── StateManager<T>
 
 CoreElement-based (non-DOM): DataProxy, DataView, Store
-Standalone: Rect, Timer, Color, DataModel, StateManager, Stylesheet, ComputedStyle,
+Standalone: Rect, Timer, Color, DataModel, Shortcuts, Stylesheet, ComputedStyle,
             SvgBuilder, X4PDFBuilder, x4_react, CMover, UnsafeHtml (extends String)
 ```
 
@@ -239,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
@@ -284,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
@@ -386,6 +389,79 @@ 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
+}
+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
+  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
+  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; root: null when empty
+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 `left`, `right` or `floats`; contents only in `content`. A panel missing from the layout is added where its kind goes.
+- 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`
@@ -1099,6 +1175,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`).
@@ -1277,17 +1393,36 @@ initTooltips(): void                                   // initialize the global
 
 ---
 
-## State (`core_state`) — Experimental
+## State (`core_state`)
 
 ```ts
-class StateManager {
-  constructor(initialState)
-  getState(path: string, defaultValue?): any
-  setState(path: string, value, context?): void
+makeState<T>(initialState: T): StateProxy<T>     // the data itself + on / off / once / watch
+
+const state = makeState({ count: 0, user: { name: '' }, items: [1, 2, 3] })
+state.on('change', e => ...)                     // EvStateChange { path, value }
+state.watch('user', e => ...)                    // 'user', anything below it, or a parent replaced; returns { off() }
+state.count++                                    // path "count"
+state.user.name = 'x'                            // path "user.name"
+state.items.push(4)                              // path "items[3]"
+
+class StateManager<T> extends EventSource<StateEvents> {
+  constructor(initialState: T)
+  proxify(): StateProxy<T>
+  on(name, listener): { off(): void }
+  off(name, listener): void
+  once(name, listener): { off(): void }
+  watch(path: string, cb: (ev: EvStateChange) => void): { off(): void }
 }
-// NOTE: marked @Experimental in the sources.
+
+// Component (protected): a state kept in localStorage under "x4@persist:<name>",
+// saved 500 ms after a change
+loadPState(name: string, defaults: Record<string, any>): any
 ```
 
+- Plain objects and arrays are proxied when read; Date, Map, Set and class instances are not.
+- Setting a property to the value it already has fires nothing.
+- Reading a property that does not exist logs an error and returns `undefined`.
+
 ---
 
 ## Common patterns
@@ -1487,7 +1622,6 @@ Optional keys: `external`, `define`, `esbuild`, `dev` (`host`, `port`, `https`,
 - The default language is `fr`. Call `selectLanguage('en')` to switch to English.
 - `Gridview` is backed by a `DataStore`; `Spreadsheet` is backed by a `Store` (different, cell-based).
 - `DataRecordID` is currently typed `any`; `strictNullChecks` is intentionally off in the recommended `tsconfig.json`.
-- `StateManager` (`core_state`) is marked **Experimental** — verify before relying on it.
 - `MonacoEditor` requires `MonacoEditor.start()` (async) before use; register extra typings with `MonacoEditor.addTypelib(name, code)`.
 - `x4_react.create_element` is the JSX pragma; 
 - `unbubbleEvents` is the set of DOM events that do not bubble through the x4 component tree.

package/package.json

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

package/src/components/colorinput/colorinput.ts

@@ -86,6 +86,7 @@ export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 	private _edit: Input;
 	private _swatches: Swatches | ( ( ) => Swatches );
 	private _popup: Popup;				// the color picker, once it was opened
+	private _closedAt = -1;				// when it closed for the last time (performance.now)
 
 	constructor( props: ColorInputProps ) {
 		super( props );
@@ -128,11 +129,12 @@ export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 		if( props.picker ) {
 			// A click on the swatch opens the picker, a second one closes it.
 			// The picker closes by itself as soon as the button goes down
-			// outside of it: whether it was open is to be known before that.
+			// outside of it, before the swatch hears of it: it was open if
+			// it closed since this very press began.
 			let wasOpen = false;
 
 			this._swatch.addClass( "picker" );
-			this._swatch.addDOMEvent( "pointerdown", ( ) => { wasOpen = !!this._popup?.isOpen( ); } );
+			this._swatch.addDOMEvent( "pointerdown", ev => { wasOpen = this._closedAt >= ev.timeStamp; } );
 			this._swatch.addDOMEvent( "click", ( ) => {
 				if( !wasOpen ) {
 					this._openPicker( );
@@ -202,6 +204,7 @@ export class ColorInput extends HBox<ColorInputProps,ColorInputEvents> {
 		} );
 
 		const popup = this._popup = new Popup( { cls: "x4colorinput-popup", autoClose: true, content: picker } );
+		popup.on( "closed", ( ) => { this._closedAt = performance.now( ); } );
 
 		// after the construction: the picker fires a first change when it is built
 		picker.on( "change", ev => {

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,279 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @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, the room of the
+	// contents, 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;
+	}
+
+	// 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 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;
+	}
+}