x4js 2.3.10 → 2.3.12

package/README.md

@@ -7,7 +7,19 @@ see [X4 home page](https://x4js.org)
 ## API Documentation
 see [GitHib](https://rlibre.github.io/x4/index.html)
 
-see [AI context](./aicontext.md)
+## Using x4js with an AI assistant
+Three files written for AI assistants ship with the package (in `node_modules/x4js/`). Give them to your assistant before asking it to write x4js code:
+
+- [aicontext.md](./aicontext.md): compact API reference, with exact signatures
+- [aiguide.md](./aiguide.md): how to write idiomatic x4js code
+- [aicli.md](./aicli.md): the `x4js` command line and `x4.config.json`
+
+With Claude Code, install the x4js plugin instead: its skill reads these files from your project by itself.
+
+```
+claude plugin marketplace add rlibre/x4
+claude plugin install x4js@rlibre
+```
 
 ---
 

package/aicli.md

@@ -0,0 +1,194 @@
+# x4js command line
+
+`x4js` creates, serves and builds x4js applications. It bundles TypeScript and styles with esbuild; there is nothing else to configure.
+
+```
+x4js create <project> [--template <name>] [--no-install]
+x4js templates
+x4js dev   [--config <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
+x4js build [--config <file>] [--debug]
+x4js --help | --version
+```
+
+## Install
+
+The command ships with the `x4js` package. In a project created by `x4js create` it is already a dependency, and the npm scripts use it:
+
+```json
+{
+	"scripts": {
+		"dev": "x4js dev",
+		"build": "x4js build"
+	}
+}
+```
+
+```
+npm run dev
+npm run build
+```
+
+Without a project yet, run it through npx: `npx x4js create my-app`.
+
+### Which x4js runs
+
+There can be two copies on a machine: the one in the project's `node_modules` and a global one (`npm install -g x4js`).
+
+| You type | Copy used |
+|---|---|
+| `npm run dev`, `npx x4js dev` | the project's own copy |
+| `x4js dev` | the global copy |
+
+A global copy older than the project's can behave differently. `dev` and `build` print their version on the first line; check it when something looks wrong.
+
+```
+x4js       2.3.11
+mode       dev
+config     C:\work\my-app\x4.config.json
+outdir     C:\work\my-app\bin
+server     http://127.0.0.1:8000
+```
+
+## Commands
+
+### `x4js create <project>`
+
+Creates a new project in the folder `<project>` from a template.
+
+| Option | Effect |
+|---|---|
+| `--template <name>`, `-t <name>` | Template to use. Default: `app`. |
+| `--no-install` | Do not run `npm install` after creating the files. |
+
+- The project name becomes the package name: lowercase letters, digits, `.`, `_` and `-` only.
+- The target folder must be empty or not exist.
+- Templates are downloaded from the `rlibre/x4-templates` repository on GitHub, so the command needs network access.
+- The `x4js` dependency of the new project is set to the version line of the command that created it (for example `2.3`).
+
+### `x4js templates`
+
+Lists the available templates with a one-line description of each.
+
+### `x4js dev`
+
+Builds the application, serves the output folder and rebuilds on every change.
+
+| Option | Effect |
+|---|---|
+| `--config <file>` | Config file to use. Default: `x4.config.json`. |
+| `--host <host>` | Address to listen on. Default: `127.0.0.1`. |
+| `--port <port>` | Port to listen on. Default: the first free port from 8000. |
+| `--http`, `--https` | Force the protocol, whatever the config says. |
+| `--open` | Open the browser once the server is ready. |
+
+- The page reloads when a source or a copied file changes. A change that only touches CSS is applied without reloading.
+- Build errors and warnings are printed in the terminal.
+- Editing the config file restarts the build.
+- HTTPS needs a certificate and a key, declared in `dev.tls` (see below).
+
+### `x4js build`
+
+Writes the application to the output folder.
+
+| Option | Effect |
+|---|---|
+| `--config <file>` | Config file to use. Default: `x4.config.json`. |
+| `--debug` | Debug build: not minified, with source maps. |
+
+The output folder is **emptied before each build**. Do not keep hand-written files in it: put them in the sources and list them in `copy`.
+
+| | `dev` | `build --debug` | `build` |
+|---|---|---|---|
+| Minified | no | no | yes |
+| Source maps | separate `.map` files | separate `.map` files | none |
+| `DEBUG_MODE` | `true` | `true` | `false` |
+| Live reload | yes | no | no |
+
+## `x4.config.json`
+
+The file sits at the root of the project. Every key is optional; without the file, the defaults below apply.
+
+```json
+{
+	"entryPoints": ["src/main.ts"],
+	"outdir": "./bin",
+	"copy": [
+		{ "from": "./src/assets", "to": "assets" },
+		{ "from": "./src/index.html", "to": "index.html" }
+	]
+}
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `entryPoints` | `["src/main.ts"]` | Files to bundle. `src/main.ts` produces `main.js` and `main.css`. |
+| `outdir` | `"./bin"` | Output folder. It cannot be the project root. |
+| `copy` | `[]` | Files or folders copied to the output after each successful build. `to` is relative to `outdir`. |
+| `external` | `[]` | Module names left out of the bundle. |
+| `define` | `{}` | Constants replaced at build time. Values are JavaScript expressions written as strings, for example `"\"prod\""`. |
+| `dev` | | Dev server settings: `host`, `port`, `https`, `tls`. |
+| `esbuild` | `{}` | Native esbuild options, applied last. They override everything above. |
+
+Relative paths are resolved from the project root. Paths accept environment variables, written `$NAME` or `${NAME}`; an undefined variable is an error.
+
+### The HTML page
+
+The command does not generate an HTML page. Write `src/index.html` and copy it with `copy`, as in the example above. It loads the bundle by its output name:
+
+```html
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta charset="utf8">
+		<link rel="stylesheet" href="main.css">
+		<script src="main.js"></script>
+	</head>
+</html>
+```
+
+### HTTPS in dev
+
+```json
+{
+	"dev": {
+		"https": true,
+		"tls": { "cert": "./certs/dev.crt", "key": "./certs/dev.key" }
+	}
+}
+```
+
+## What the build handles
+
+| Import | Result |
+|---|---|
+| `.ts`, `.js` | Bundled into one script per entry point (browser, ES2020). |
+| `.scss`, `.sass`, `.css` | Compiled and bundled into one stylesheet per entry point. |
+| `.less` | Same, if the `less` package is installed in the project (`npm install -D less`). |
+| `.svg` imported from a script | A `data:` URL string, usable as an icon. |
+| `.png`, `.jpg`, `.jpeg`, `.ttf`, `.woff`, `.woff2` | Copied to `assets/` with a hashed name. |
+
+Two constants are always defined:
+
+| Constant | Value |
+|---|---|
+| `DEBUG_MODE` | `true` in `dev` and `build --debug`, `false` in `build`. |
+| `VERSION_ID` | Build date as a number, `YYMMDD`. |
+
+Declare them once in your project to use them from TypeScript:
+
+```ts
+declare const DEBUG_MODE: boolean;
+declare const VERSION_ID: number;
+```
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `index.html` is missing from the output folder | It is not listed in `copy`, or the command that ran is an older global copy. Compare the version on the first line with the project's. |
+| A file placed in the output folder disappeared | `x4js build` empties the folder. Move the file to the sources and add it to `copy`. |
+| `Cannot find package 'esbuild'` | The dependencies of the `x4js` copy being run are not installed. Run `npm install` in the project. |
+| `Config file not found` | The file given to `--config` does not exist. Without `--config`, a missing `x4.config.json` is not an error. |
+| `Environment variable '…' is not defined` | A path in the config uses `$NAME` and the variable is not set. |
+| `LESS support requires the "less" package` | A `.less` file is imported and `less` is not installed in the project. |
+| No colors in the terminal, or unwanted ones | Set `FORCE_COLOR=1` to force them, `NO_COLOR=1` to remove them. |

package/aicontext.md

@@ -17,6 +17,7 @@ import { ... } from 'x4js'   // src/x4.ts
 **Archived repository**: https://github.com/rlibre/x4js (read-only since March 2026)
 **License**: MIT
 **Quick start**: `npx x4js create demo` (list the templates with `npx x4js templates`)
+**Claude Code plugin**: `claude plugin marketplace add rlibre/x4` then `claude plugin install x4js@rlibre` (skill that reads these files from the project)
 
 ---
 
@@ -26,7 +27,7 @@ import { ... } from 'x4js'   // src/x4.ts
 CoreElement<E>                 named timers + event surface (no DOM)
   ├── Component<P,E>           base DOM component
   │     ├── Box<P,E>
-  │     │     ├── HBox / VBox
+  │     │     ├── HBox / VBox → HSplitBox / VSplitBox
   │     │     ├── StackBox → AssistBox
   │     │     ├── GridBox / MasonryBox
   │     │     ├── Form
@@ -35,10 +36,11 @@ CoreElement<E>                 named timers + event surface (no DOM)
   │     │     ├── BtnGroup, Tabs, Video, Saturation
   │     ├── Button, Input, Icon, Label, SimpleText, Checkbox, Radio, Link
   │     ├── Listbox, Gridview, Treeview, Select, Combobox, Slider, Gauge
-  │     ├── Progress, TickLine, Canvas, Image, SvgComponent, Spreadsheet, MonacoEditor
+  │     ├── Progress, TickLine, Canvas, Image, Spreadsheet, MonacoEditor
+  │     ├── SvgComponent → Chart
   │     ├── CSizer → HSizer / VSizer
   │     ├── FileDialog, ScrollView, Viewport, Flex, Space
-  │     ├── HBox-based: ColorInput, Rating, Switch, Keyboard, TextEdit, Breadcrumbs
+  │     ├── 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
 
@@ -608,6 +610,26 @@ class Combobox extends Component {
 }
 ```
 
+### `AutoComplete` — text field with on-demand suggestions
+
+```ts
+interface AutoCompleteProps extends TextEditProps {   // label, labelWidth, required, placeholder, value...
+  search: (ev: EvSearch) => void            // required; ev.text, ev.setItems(items) — may be called async
+  change?                                   // EvAutoCompleteChange { value, item /* null = free text */ }
+  strict?: boolean                          // only a picked item (or empty) is accepted; default false
+  itemValue?: "text" | "id"                 // what goes into the field when an item is picked; default "text"
+  delay?: number                            // ms before search, default 250
+  minChars?: number                         // default 1
+  renderer?: (item: ListItem) => Component
+}
+class AutoComplete extends TextEdit {
+  getSelection(): ListboxID                 // id of the picked item, undefined for a free text
+  setSelection(item: ListItem): void;  showDropDown(): void
+}
+// Use Combobox for a fixed, known list; AutoComplete when suggestions come from a search (server).
+// In a Form the value is the field content (text or id, per itemValue).
+```
+
 ### `ColorInput`
 
 ```ts
@@ -710,12 +732,32 @@ interface SpreadsheetProps extends ComponentProps {
   columns: SpreadsheetColumn[]              // required
   footer?: boolean
   rowClassifier?: RowClassifier
+  enterMove?: "down" | "right" | "none"     // selection move after Enter in a cell editor (default "down")
   click?, dblClick?, contextMenu?, selectionChange?
+  cellChange?                               // EvCellChange, fired before an edited value is written to the store
+  cellKey?                                  // EvCellKey { key, row, col, uievent }, fired for each key before the default handling
+}
+interface SpreadsheetColumn {               // GridColumn +
+  editable?: boolean | ((row, col) => boolean)       // inline edition (off by default), col = column index
+  editor?: (row, col, value) => Component            // custom editor, must implement queryInterface("form-element")
 }
+interface EvCellChange { row; col /* index */; colId /* store key */; value /* writable */; oldValue }
 class Spreadsheet extends Component {
   getSelection(): /* cell */; navigate(sens: kbNav): boolean; lock(lock): void
+  editCell(row, col, clear = false): boolean         // cell must be visible
+  stopEdit(commit = true): void;  isEditing(): boolean
 }
 
+// Inline edition: F2 / Enter / double-click / typing starts, Enter / Tab / click elsewhere validates, Escape cancels,
+// Delete clears, editable checkboxes toggle on double-click or Space (a single click only selects).
+// Default editor is an Input matching the column type.
+// cellKey: key hook (function keys...), not fired while a cell is edited; ev.preventDefault() skips the default handling.
+// cellChange: ev.preventDefault() refuses the value, ev.value can be replaced.
+// Select / Combobox in a cell (the store holds the id, use `formatter` to display the text):
+//   { id: 2, title: "Status", width: 120, editable: true,
+//     formatter: ( id ) => states.find( x => x.id===id )?.text,
+//     editor: ( row, col, value ) => new Select( { items: states, value } ) }
+
 // Store: in-memory cell store (extends CoreElement)
 class Store extends CoreElement {
   setData(row, col, data): void;  getData(row, col): any;  hasData(row, col?): boolean
@@ -724,6 +766,28 @@ class Store extends CoreElement {
 }
 ```
 
+### `Chart` — minimal svg chart (line, area, bar, pie, donut)
+
+```ts
+interface ChartProps extends SvgProps {
+  type?: "line" | "area" | "bar" | "pie" | "donut"   // default "line"
+  series: ChartSerie[]                      // required; pie & donut use the first serie
+  labels?: string[]                         // default: 1, 2, 3...
+  xaxis?: ChartAxis;  yaxis?: ChartAxis     // { name?, ticks?, min?, max?, step? }, all computed by default
+  legend?: boolean                          // default: shown when 2+ named series
+  stacked?: boolean
+  formatter?: (value: number) => string     // default: chartFormatUnit (1.5k, 2M...)
+  click?                                    // EvChartClick { serie, index, value }
+}
+interface ChartSerie { name?; values: number[] /* undefined = hole */; color?; fill?; dots? }
+class Chart extends SvgComponent {
+  setType(type): void;  setSeries(series, labels?): void;  setLabels(labels): void
+  setTicks(sens: "x" | "y", ticks: ChartTick[]): void
+}
+// Colors: CSS variables --chart-color-1..8 (or serie.color). Size it with width/height/flex like any component.
+// Minimal by design: no dual axis, mixed types, time axis, zoom or animation — use a dedicated library for those.
+```
+
 ### `PropertyGrid`
 
 ```ts
@@ -894,6 +958,13 @@ class Form extends Box {
 ## Sizers / viewport / misc
 
 ```ts
+// PREFERRED for resizable panels: HSplitBox / VSplitBox (sizers are inserted automatically between panels).
+// The panel with `flex` takes the remaining space, its neighbour is the one resized.
+class HSplitBox extends HBox               // panels side by side, resizable width:  { content: Component[] }
+class VSplitBox extends VBox               // panels stacked, resizable height:      { content: Component[] }
+// 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 HSizer extends CSizer                // horizontal splitter
 class VSizer extends CSizer                // vertical splitter
@@ -1325,6 +1396,7 @@ When creating a new x4js project, use these files as a base.
 
 `x4js dev` runs the dev server, `x4js build` writes `outdir` (add `--debug` for a debug build).
 Both read `x4.config.json` (change the file with `--config <file>`).
+Full reference of the command line (commands, options, config keys, troubleshooting): `aicli.md`.
 
 ### `x4.config.json`
 

package/aiguide.md

@@ -132,6 +132,23 @@ super();
 
 when the component expects props.
 
+When writing a custom component, pass the whole props object: do not remove your own values from it before calling `super`. The base class keeps what it receives in `this.props`, so they stay readable later.
+
+```ts
+// avoid: search and strict are lost for this.props
+const { search, strict, ...base } = props;
+super(base);
+
+// prefer: override only what must not reach the parent
+super({ ...props, type: "text" });
+```
+
+Connect the event callbacks given in props with `mapPropEvents`, not with hand-written `if (props.x) this.on(...)`:
+
+```ts
+this.mapPropEvents(props, "change", "search");
+```
+
 For derived application components, prefer building the component's main content explicitly after `super(props)`.
 
 Ordinary nested x4 components may naturally use their `content` property where convenient.
@@ -192,6 +209,10 @@ Component objects
 Real DOM
 ```
 
+`addDOMEvent` belongs to custom components (a canvas-based widget, for example).
+
+On standard components, use their props and events.
+
 ---
 
 ## 6. Objects vs JSX
@@ -327,6 +348,12 @@ export const deviceModel = new DeviceModel();
 
 A model may encapsulate server access directly.
 
+Views should never call `fetch`.
+
+All server access goes through model classes deriving from one base class that owns the single `fetch` call (timeout, network failure, HTTP status, expired session, fetch mask).
+
+Create one model per functional domain. It normally corresponds to one URL root.
+
 Keep responsibilities simple:
 
 ```text id="t39sbp"
@@ -467,6 +494,18 @@ Do not introduce a JavaScript theme abstraction simply to mirror CSS variables.
 
 Presentation belongs in CSS when CSS already solves the problem.
 
+CSS styles a component; it never removes behaviour.
+
+Do not hide a control a component creates: configure the component through its props (for example `closable: false`).
+
+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 dark theme gets its own scale.
+
 ---
 
 ## 19. Browser and TypeScript capabilities
@@ -578,6 +617,34 @@ The goal is to build the application with the smallest set of mechanisms that ke
 
 ---
 
+## 23. Translations
+
+x4 starts in French.
+
+Application texts are declared with `addTranslation` for each language.
+
+Select the language before any component is built, since a component reads its texts at construction.
+
+Call `selectLanguage` after `addTranslation`:
+
+```ts
+addTranslation("fr", { /* ... */ });
+addTranslation("en", { /* ... */ });
+
+selectLanguage("en");
+
+// only now build the application components
+```
+
+Type each additional language after the first one, so the compiler reports a missing text:
+
+```ts
+const app_fr = { app: { open: "Ouvrir", close: "Fermer" } };
+const app_en: typeof app_fr = { app: { open: "Open", close: "Close" } };
+```
+
+---
+
 ## Final rule
 
 When generating x4 code:

package/cli/main.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { failure } from "./log.mjs";
+import { failure, info } from "./log.mjs";
 
 const cliDir = path.dirname(fileURLToPath(import.meta.url));
 const packageFile = path.join(cliDir, "..", "package.json");
@@ -46,11 +46,13 @@ try {
             break;
         }
         case "dev": {
+            info("x4js", version);
             const { dev } = await import("./dev.mjs");
             await dev(argv);
             break;
         }
         case "build": {
+            info("x4js", version);
             const { build } = await import("./build.mjs");
             await build(argv);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.3.10",
+  "version": "2.3.12",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",
@@ -21,6 +21,7 @@
     "src",
     "bin",
     "cli",
+    "aicli.md",
     "aicontext.md",
     "aiguide.md",
     "README.md",

package/src/components/autocomplete/autocomplete.module.scss

@@ -0,0 +1,28 @@
+/**
+ *  ___  ___ __
+ *  \  \/  /  / _
+ *   \    /  /_| |_
+ *   /    \____   _|
+ *  /__/\__\   |_|
+ *
+ * @file autocomplete.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.
+ **/
+
+// the field itself is a textedit
+
+.x4dropdownlist.autocomplete {
+	.x4item {
+		gap: 8px;
+
+		.id {
+			font-weight: 500;
+			min-width: 4em;
+		}
+	}
+}