x4js 2.3.17 → 2.3.19

package/aicli.md

@@ -7,7 +7,7 @@ x4js create <project> [--template <name>] [--no-install]
 x4js templates
 x4js dev   [--config <file>] [--env <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
 x4js build [--config <file>] [--env <file>] [--debug]
-x4js --help | --version
+x4js [<command>] --help | --version
 ```
 
 ## Install
@@ -124,7 +124,7 @@ The file sits at the root of the project. Every key is optional; without the fil
 | 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. |
+| `outdir` | `"./bin"` | Output folder. It cannot be the project root, nor a folder that contains it. |
 | `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\""`. |
@@ -240,7 +240,7 @@ declare const VERSION_ID: number;
 
 | 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. |
+| `index.html` is missing from the output folder | `copy: not found: …` in the output: its `from` does not exist. Or 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. |

package/aicontext.md

@@ -34,13 +34,13 @@ CoreElement<E>                 named timers + event surface (no DOM)
   │     │     ├── Popup → Dialog → MessageBox / InputBox / PromptBox / ProgressionBox
   │     │     │        → Menu, DropdownList, Notification
   │     │     ├── BtnGroup, Tabs, Video, Saturation
-  │     ├── Button, Input, Icon, Label, SimpleText, Checkbox, Radio, Link
+  │     ├── Button, Input, Icon, Label, SimpleText, Checkbox, Radio, Link, SimpleTextArea
   │     ├── Listbox, Gridview, Treeview, Select, Combobox, Slider, Gauge
   │     ├── Progress, TickLine, Canvas, Image, Spreadsheet, MonacoEditor
   │     ├── SvgComponent → Chart
   │     ├── CSizer → HSizer / VSizer
   │     ├── FileDialog, ScrollView, Viewport, DockingView, Flex, Space
-  │     ├── HBox-based: ColorInput, Rating, Switch, Keyboard, TextEdit → AutoComplete, Breadcrumbs
+  │     ├── HBox-based: ColorInput, Rating, Switch, Tag, Keyboard, TextEdit → AutoComplete, Breadcrumbs
   │     └── VBox-based: Calendar, ColorPicker, FileDrop, Panel, PropertyGrid, TextArea
   └── Application<E>           singleton, no DOM of its own
 
@@ -228,7 +228,7 @@ static parentElement<T>(dom: Node, cls?: Constructor<T>): T
 ```ts
 show(vis?: boolean): this              // toggles "x4hidden" class (not display:none)
 hide(): this
-enable(ena?: boolean): this            // sets "disabled" + propagates to child <input>/<button>
+enable(ena?: boolean): this            // sets or removes "disabled" and "inert" on the component
 disable(): this
 isDisabled(): string | null
 isVisible(): boolean
@@ -279,7 +279,7 @@ Singleton. Extends `CoreElement` (no DOM of its own). (`src/core/core_applicatio
 interface AppProps { mountPoint?: string }   // CSS selector, default "body"
 
 constructor(props?: AppProps)                // auto-mounts the mainview on page load
-setMainView(view: Component): void
+setMainView(view: Component): void           // once, in the constructor of the app: each call sets up the keyboard (Tab, shortcuts) again
 getMainView(): Component
 static instance<P extends Application>(): P
 setEnv(name: string, value: any): void
@@ -537,6 +537,23 @@ class Image extends Component {
 }
 ```
 
+### `Tag` — a short text in a rounded frame, with an icon
+
+```ts
+interface TagProps extends ComponentProps {
+  label?: string | UnsafeHtml              // the text: `label`, not `text` as in Label
+  icon?: string
+}
+class Tag extends HBox {}                  // no method: its text and its icon are those of its props
+// cls "alert": the colors of an alert
+// CSS vars: --tag-background --tag-color --tag-icon-color --tag-border
+```
+
+```ts
+new Tag({ label: 'Draft' })
+new Tag({ label: 'Late', icon: 'assets/clock.svg', cls: 'alert' })
+```
+
 ### `Progress`
 
 ```ts
@@ -560,7 +577,7 @@ class Gauge extends Component {
 
 ```ts
 interface RatingProps extends ComponentProps {
-  value?: number; steps?: number; icon?: string; name?: string
+  value?: number; steps?: number; icon?: string; name?: string   // value: the count of stars lit (0 to steps), the star of the value clicked again gives 0; steps: 5 by default; name: for a Form, which reads a number
   change?: EventCallback<EvChange>
 }
 class Rating extends HBox {
@@ -581,12 +598,12 @@ type InputProps = TextInputProps | CheckboxProps | RadioProps | RangeProps
 
 interface BaseProps extends ComponentProps {
   name?: string                            // required for Form.getValues/setValues
-  autofocus?: boolean; required?: boolean; readonly?: boolean; placeholder?: string
+  autofocus?: boolean; required?: boolean; readonly?: boolean; placeholder?: string   // required, readonly: not on checkbox, radio; placeholder: text, email, password, number
   focus?: EventCallback<EvFocus>; change?: EventCallback<EvChange>
 }
 // TextInputProps: type?: "text"|"email"|"password"; value?: string|number; maxlength?, minlength?,
 //                 pattern?, spellcheck?, trim?
-// NumberProps:    type: "number"; value?: string|number; min?, max?, step?
+// NumberProps:    type: "number"; value?: string|number; min?, max?, step?   // as many decimals shown as the step, 4 at most
 // RangeProps:     type: "range"; min: number; max: number; step?; value?: number
 // DateProps:      type: "date"; value?: string|Date
 // TimeProps:      type: "time"; value?: string
@@ -614,22 +631,44 @@ type TextEditProps = (TextInputProps | NumberProps | DateProps | TimeProps) & {
   labelWidth?: number; inputWidth?: number; inputId?: string
   inputGadgets?: Component[]; inputAttrs?: any
 }
+// style, tooltip, hidden, flex, stretch, height: on the box (label + field); dom_events: on the input
 class TextEdit extends HBox {
   getValue(): string; setValue(value: string): void; getInput(): Input
 }
 ```
 
-### `TextArea`
+### `TextArea`, `SimpleTextArea` — native `<textarea>`, with or without a label
 
 ```ts
-interface TextAreaProps extends BaseProps {      // BaseProps: see Input (name, readonly, placeholder...)
-  label?: string; value?: string
-  resize?: boolean | "none" | "vertical" | "horizontal" | "both"
+interface SimpleTextAreaProps extends BaseProps {   // BaseProps: see Input (name, readonly, required, placeholder, autofocus, focus, change)
+  value?: string
+  resize?: boolean | "none" | "vertical" | "horizontal" | "both"   // no handle by default; true = "both", false = "none"
   trim?: boolean                           // getText() trims, unless false
 }
-class TextArea extends VBox { getText(): string; setText(text: string): void }
+interface TextAreaProps extends SimpleTextAreaProps { label?: string }
+
+class SimpleTextArea extends Component {    // the <textarea> alone
+  getText(): string; setText(text: string): void
+  scrollToBottom(): void
+  isValid(): boolean                       // false when it is required and empty
+}
+class TextArea extends VBox {               // a Label above a SimpleTextArea
+  getText(): string; setText(text: string): void
+  scrollToBottom(): void
+  isValid(): boolean
+}
 ```
 
+```ts
+new TextArea({ label: 'Comment', name: 'comment', placeholder: 'A few words...', resize: 'vertical' })   // in a form
+new SimpleTextArea({ flex: 1, placeholder: 'Your message', resize: false })                              // no label
+```
+
+- `TextArea` in a form; `SimpleTextArea` where a label has no place (a message to type, a log).
+- Both are form elements: with a `name`, `Form.getValues()` and `setValues()` read and write them.
+- The value is read and written with `getText()` / `setText()`, not `getValue()` / `setValue()`.
+- `change` is fired at each key that is typed, with the text as `ev.value`; `focus` when the focus comes and goes (`ev.focus_out`). As for an `Input`.
+- `required`: an empty text is not valid. `Form.validate()` then returns `null`, or tells its validator that the form is not valid.
 ### `Checkbox`
 
 ```ts
@@ -637,6 +676,7 @@ interface CheckboxProps extends ComponentProps {
   label: string; checked?: boolean; value?: boolean|number|string; name?: string
   change?: EventCallback<EvChange>
 }
+// in a Form: without value (or a boolean one), a boolean; with one, the value when checked, null when not
 class Checkbox extends Component {
   getCheck(): boolean; setCheck(ck: boolean): void
   setLabel(text: string): void; toggle(): void
@@ -657,15 +697,15 @@ interface RadioProps extends ComponentProps {
 class Radio extends Component {
   getValue(): string; setCheck(ck: boolean): void
   setLabel(text: string): void
-  checkValue(vname: string): void          // check the radio whose value === vname (group)
+  checkValue(vname: string): void          // check the radio whose value === vname, in the group of its form (else of the page)
 }
 ```
 
 ### `Switch`
 
 ```ts
-interface SwitchProps extends ComponentProps { label: string; checked?: boolean; name?: string }
-// with a name, a Form reads and writes it as a boolean
+interface SwitchProps extends ComponentProps { label: string; checked?: boolean; value?: string; name?: string }
+// with a name, a Form reads and writes it: a boolean, or with a value, the value when checked and null when not
 class Switch extends HBox {}
 ```
 
@@ -675,10 +715,12 @@ class Switch extends HBox {}
 interface SliderProps extends ComponentProps {
   value: number; min: number; max: number  // required
   step?: number; vertical?: boolean
-  change?: EventCallback<EvChange>
+  name?: string                            // for a Form, which reads a number
+  change?: EventCallback<EvChange>         // when the user moves the thumb (drag, arrows), not by the code
 }
 class Slider extends Component {
-  setMin(min: number): void; setMax(max: number): void; setValue(v: number): void
+  getValue(): number
+  setMin(min: number): void; setMax(max: number): void; setValue(v: number): void   // the value is kept between min and max, on the step
 }
 ```
 
@@ -708,13 +750,13 @@ interface ComboboxProps extends ComponentProps {
   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>
+  selectionChange?: EventCallback<EvSelectionChange>   // at each item reached with the arrows too
 }
 class Combobox extends Component {
   getValue(): string; setValue(value: string): void
   getInput(): Input
-  getSelection(): ListboxID
-  selectItem(index: number): void
+  getSelection(): ListboxID                // the item chosen (click or arrows); undefined when the text typed is not the one of an item
+  selectItem(index: ListboxID): void       // null: none, the field is emptied
   setItems(items): void
   showDropDown(): void
 }
@@ -784,10 +826,13 @@ interface ListboxProps extends Omit<ComponentProps,"content"> {
   title?: string; icon?: string
   header?: Header; footer?: Component
   checkable?: true; multisel?: true
+  emptyMsg?: string                        // shown in place of the items while there are none
   dblClick?: EventCallback<EvDblClick>
   selectionChange?: EventCallback<EvSelectionChange>
   contextMenu?: EventCallback<EvContextMenu>
 }
+// 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".
 class Listbox extends Component {
   setItems(items: ListItem[], keepSel?: boolean): void
   appendItem(item: ListItem, prepend?: boolean, select?: boolean): void
@@ -801,7 +846,6 @@ class Listbox extends Component {
   ensureSelectionVisible(): void
   renderItem(item: ListItem): Component     // override to customize
   defaultRenderer(item: ListItem): Component
-  preventFocus: boolean
 }
 ```
 
@@ -812,38 +856,51 @@ interface GridviewProps extends ComponentProps {
   store: DataStore                          // required
   columns: GridColumn[]                     // required
   footer?: boolean; emptyMsg?: string
-  sort?: object
-  click?: EventCallback<EvClick>
-  dblClick?: EventCallback<EvDblClick>
+  multisel?: boolean                        // Ctrl+click adds or removes a row, Shift+click a range, Ctrl+A all
+  sort?: { field_id: string; asc?: boolean }   // the first sort; ascending only when asc is true
+  click?: EventCallback<EvClick>               // a click on a row; ev.context is its record
+  dblClick?: EventCallback<EvDblClick>         // ev.context is the record of the row
   contextMenu?: EventCallback<EvContextMenu>
   selectionChange?: EventCallback<EvSelectionChange>
 }
 class Gridview extends Component {
   setStore(store: DataStore): void
-  setColumns(columns: GridColumn[]): void
   setColTitle(col_name: string, title: string): void
-  sortCol(colIdx: number, ascending: boolean): void
+  sortCol(colId: any, ascending: boolean): void     // colId: the id of the column, not its index
   getView(): DataView
-  getSelection(): DataRecord[]
-  getFirstSel(): DataRecord
+  getSelection(): DataRecord[]              // null when nothing is selected
+  getFirstSel(): DataRecord                 // null when nothing is selected
   selectItem(id, ensureVisible?: boolean): void
   clearSelection(): void
+  selectAll(): void                         // multisel only; keeps the id of every record: costs memory on a very large view
   navigate(sens: kbNav): boolean
   lock(lock: boolean): void
 }
+// Selection: the selected records, not their rows. It survives a sort; a record that leaves the view (filter, delete) leaves it, with a selectionChange.
+// getSelection(): every selected record, or null. selectionChange: ev.selection has them all.
+// Column sizer: dragging it gives the column that width (it is not flex anymore); a double click on it makes the column flex again.
 ```
 
 ### `Treeview`
 
 ```ts
 interface TreeItem extends ListItem { children?: TreeItem[]; open?: boolean }
-interface TreeviewProps extends ComponentProps { /* items, renderer... */ }
+interface TreeviewProps extends Omit<ComponentProps,"content"> {
+  items: TreeItem[]                         // required
+  footer?: Component
+  emptyMsg?: string                        // shown in place of the items while there are none
+  click?: EventCallback<EvClick>
+  dblClick?: EventCallback<EvDblClick>
+  selectionChange?: EventCallback<EvSelectionChange>
+}
+// emptyMsg: as for a Listbox. Without it the text is _tr.global.empty_list ("Empty list").
+// There is no `renderer`: an item is drawn from its `text`, `iconId`, `cls` and `sub_cols`.
 class Treeview extends Component {
   setItems(items: TreeItem[]): void
-  getSelection(): ListboxID
-  selectItem(id): void
+  getSelection(): ListboxID                 // one item, not an array
+  selectItem(id: ListboxID): void
   clearSelection(): void
-  navigate(sens: kbNav): boolean            // see kbTreeNav enum
+  navigate(sens: kbTreeNav): boolean        // first, prev, next, last, parent, child, expand, collapse, toggle
 }
 ```
 
@@ -871,6 +928,7 @@ class Spreadsheet extends Component {
   stopEdit(commit = true): void;  isEditing(): boolean
 }
 
+// Column sizer: dragging it gives the column that width (it is not flex anymore); a double click on it makes the column flex again.
 // 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.
@@ -1029,7 +1087,7 @@ class Dialog extends Popup {
   getButton(name: string): Button
   getBtnBar(): BtnGroup
   setTitle(title: string): void
-  showAsync(): Promise<string>             // resolves with the clicked button name
+  showAsync(): Promise<string>             // the name of the clicked button; null when closed without a button (Escape, close box)
 }
 ```
 
@@ -1042,7 +1100,7 @@ class MessageBox extends Dialog {
 }
 class InputBox extends Dialog {
   getValue(): string
-  // static showAsync(msg, value, title?, options?: {password?, trim?}): Promise<string>  (null if cancelled)
+  // static showAsync(msg, value, title?, options?: {password?, trim?}): Promise<string>  (null if cancelled or closed)
 }
 class PromptBox extends Dialog {
   static showAsync(msg: string|UnsafeHtml, editor: Component, title?: string): Promise<string>
@@ -1080,8 +1138,8 @@ class Form extends Box {
   setValues(values: FormValues): void
   getValues<T extends FormValues>(): T
   setAutoComplete(on?: boolean): void
-  setValidator(validator: (values: FormValues, is_valid: boolean) => boolean): void
-  validate(): FormValues                   // null if invalid
+  setValidator(validator: (values: FormValues, is_valid: boolean) => boolean): void   // a new call replaces the validator
+  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").
 ```
@@ -1110,13 +1168,22 @@ class Video extends Box {
   get volume(): number; get videoWidth(): number; get videoHeight(): number
   set stream(stream: MediaStream)
 }
-class Calendar extends VBox { getDate(): Date; setDate(date: Date): void }
+class Calendar extends VBox {               // props: date?, minDate?, maxDate? (days out of them cannot be chosen), change ("change": the day clicked)
+  getDate(): Date; setDate(date: Date): void   // copies: the calendar keeps its own date
+}
 class ColorPicker extends VBox {           // props: color, swatches?, nullable?; "change": EvColorChange, also fired once when built
   getColor(): Color; setColor(color: Color | string): void; setSwatches(swatches): void
 }
 class Panel extends VBox { setTitle(title: string): void }
 class Breadcrumbs extends HBox { setItems(elements): void }
-class Keyboard extends HBox                // virtual keyboard
+interface KeyboardProps extends BoxProps { locale?: string }   // "fr-FR" (default), "de-CH", "pl"...
+class Keyboard extends HBox {               // virtual keyboard, shown while an <input> has the focus
+  setLocale(locale: string): void
+  setZoom(perc: number): void
+  showOn(el: Component): void
+}
+// languages: cs da de en es et fi fr ga hr hu it lt lv mt nl pl pt ro sk sl sv
+// bottom row: 123 (numeric pad), the letters of the language (éè, none in en), the signs (#+=); Abc comes back
 class TickLine extends Component
 class Header extends HBox                  // resizable column header; updates target style "--{name}-width"
 ```
@@ -1177,7 +1244,7 @@ class DataStore<T> extends EventSource {
 ```ts
 interface FilterInfo {
   op: "<"|">"|"<="|"="|">="|"<>"|"empty-result"|FilterFunc
-  field?: string; value?: string|RegExp; caseSensitive?: boolean
+  field?: string; value?: string|number|RegExp; caseSensitive?: boolean   // a RegExp is tested on the field as it is: caseSensitive does not apply, the regexp handles the case (/^jo/i)
 }
 interface SortProp { field: string; ascending: boolean; numeric?: boolean; callback?: SortCallback }
 // Event "view_change" → { change_type: "change"|"filter"|"sort" }
@@ -1189,6 +1256,8 @@ class DataView extends CoreElement {
   getRecId(rec): any; indexOfId(id): number
   getStore(): DataStore; getModel(): DataModel
   forEach(cb): void; changed(): void
+  close(): void                            // stops following the store; call it on a view you made (createView) and do not use anymore
+  open(): void                             // follows the store again after a close(), filtered and sorted with its data of the moment
 }
 ```
 
@@ -1206,7 +1275,7 @@ class DataProxy extends CoreElement { load(url?): Promise<void> }   // Event "ch
 ```ts
 class Router extends EventSource {
   constructor(useHash?: boolean)           // default true (# URLs)
-  get(uri: string|RegExp, handler: (params: any, path: string) => void): void
+  get(uri: string|RegExp, handler: (params: any, path: string) => void): void   // the first route that matches is called, in the order of get: "/*" last is the route for the rest (params.wild)
   init(): void                             // trigger the current route
   navigate(uri: string, notify?: boolean, replace?: boolean): boolean
   // Events: "change" → { value: string } ; "error" → { code: 404, message: string }
@@ -1256,6 +1325,80 @@ class MyView extends VBox {
 
 ---
 
+## Clipboard (`core_clipboard`)
+
+The clipboard of the system: a text, an image, files. Never call `navigator.clipboard` or `ev.clipboardData`.
+
+```ts
+interface ClipboardContent { text?: string; image?: Blob }
+interface ClipboardRead extends ClipboardContent { files: File[] }   // files: only in an event
+
+// from a menu or a button: asynchronous, never fail
+setClipboard(data: ClipboardContent): Promise<boolean>   // false: the system refused
+getClipboard(): Promise<ClipboardRead>
+canReadClipboard(): boolean                              // false: nothing to paste, disable the item
+
+// in a "copy", "cut" or "paste" event
+setEventClipboard(ev: ClipboardEvent, data: ClipboardContent): void   // prevents the default
+getEventClipboard(ev: ClipboardEvent): ClipboardRead                  // synchronous, default left as it is
+```
+
+```ts
+this.addDOMEvent('copy', ev => setEventClipboard(ev, { text: this.getSelectedText() }))
+
+this.addDOMEvent('paste', ev => {
+  const data = getEventClipboard(ev)
+  if (data.image) {
+    ev.preventDefault()
+    this.setPicture(data.image)
+  }
+})
+
+new Button({ label: 'Paste', click: async () => {
+  const data = await getClipboard()
+  if (data.text) this.insert(data.text)
+} })
+```
+
+- The keys of the user (Ctrl+C, Ctrl+V) are the `copy`, `cut` and `paste` events, not shortcuts: the browser then gives its clipboard without asking for a permission.
+- The events go to the component that has the focus: give it a `tabindex`.
+- Out of an event, the browser may refuse, and there is no system clipboard on a page that is not served in https. What the application set last is then what `getClipboard` gives: copy and paste still work inside the application.
+- An image is written as a PNG; another format is converted. Files can be read in a `paste` event only, and cannot be written.
+
+---
+
+## Drag and drop (`core_dragdrop`)
+
+`dragManager` makes a component something the user drags, and another one a place where things are dropped: components of the application, or files that come from the desktop.
+
+```ts
+interface DropInfo { pt: Point; data: DataTransfer }
+type DropCallback = (command: 'enter' | 'leave' | 'drag' | 'drop', el: Component, infos: DropInfo) => void
+type DropFilterCallback = (el: Component, data: DataTransfer) => boolean   // false: nothing can be dropped here
+
+dragManager.registerDraggableElement(el: Component): void
+dragManager.registerDropTarget(el: Component, cb: DropCallback, filterCB?: DropFilterCallback): void
+```
+
+```ts
+dragManager.registerDraggableElement(card)
+
+dragManager.registerDropTarget(column, (cmd, el, infos) => {
+  if (cmd == 'drop') {
+    if (infos.data.files.length) this.upload(infos.data.files)   // files from the desktop
+    else this.moveCard(el, infos.pt)                              // el: the component that was dragged
+  }
+})
+```
+
+- `registerDraggableElement`: while it is dragged, the component has the class `dragging`, and a copy of it with the class `dragged`, added to the body, follows the pointer. Nothing else is done: no data of the application goes with the drag, the target gets the component itself.
+- The callback of a target: `enter` and `leave` when the pointer comes over it and goes away, `drag` again and again while it is over it, `drop`. Only `drag` and `drop` have `infos`; `pt` is in the coordinates of the page.
+- `enter` and `leave` are found by a timer: they may come up to 300 ms late, and a `leave` also follows a `drop`. Between them the target has the class `drop-over`.
+- `el` in the callbacks is the dragged component, not the target. There is none for files that come from the desktop: read `infos.data.files`.
+- `Image` (`candrop`) and `FileDrop` already use it for files.
+
+---
+
 ## i18n (`core_i18n`)
 
 Two built-in languages (`fr` default, and `en`).
@@ -1319,7 +1462,7 @@ centerRect(inner: IRect, outer: IRect, margin?): IRect
 sprintf(format, ...args): string           // replaces {0} {1}...
 pad(what, size, ch?): string               // >0 padEnd, <0 padStart
 pascalCase(s): string; camelCase(s): string; clamp<T>(v, min, max): T
-measureText(str, size): number
+measureText(str, size, bold?): number      // width in Helvetica, from core_pdf (see PDF)
 
 // Dates
 date_format(date, options?): string
@@ -1351,8 +1494,9 @@ interface ITabHandler  { focusNext(next: boolean): boolean }
 interface ITipHandler  { getTip(): string }
 
 // Other variables
-const dragManager; const svgLoader; const linearColorStops; const simpleColorStop
-const unbubbleEvents       // set of DOM event names that do NOT bubble through the x4 tree
+const dragManager                           // see Drag and drop
+const svgLoader; const linearColorStops; const simpleColorStop
+const unbubbleEvents       // the events that stay on their node: see "Important stupid notes"
 const makeUniqueComponentId  // () => string, "x4-<n>" (exported as a value)
 ```
 
@@ -1389,10 +1533,29 @@ class SvgBuilder extends SvgGroup {
 ## PDF (`core_pdf`)
 
 ```ts
+interface PDFProps { title?: string; author?: string; subject?: string }
 class X4PDFBuilder {
-  page(width: number, height: number, callback): void
+  constructor(props?: PDFProps)
+  page(width: number, height: number, callback: (ctx: PageContext) => void): void   // points; without size 612 x 792
   build(): Uint8Array
-}
+  buildAsync(): Promise<Uint8Array>          // streams compressed (FlateDecode)
+}
+export interface PageContext {                // origin bottom left, y goes up
+  text(str, x, y, size, opts?: { align?: 'left'|'center'|'right'; width?; color?; bold? }): void
+  rect(x, y, w, h, fill: string): void
+  line(x1, y1, x2, y2, stroke: string, lineWidth?): void
+  path(segments: PathSegment[], fill: string, stroke?: string, lineWidth?): void   // null: not drawn
+  image(jpegBytes: Uint8Array, x, y, w, h): void
+  link(url, x, y, w, h, opts?: { underline?: string }): void
+  barcode(type: BarcodeType, text, x, y, w, h, opts?: BarcodeOptions): void   // datamatrix: square min(w,h), (x,y) bottom left; code128: bars on w x h; no quiet zone
+}
+type PathSegment = ['m', x, y] | ['l', x, y] | ['c', x1, y1, x2, y2, x3, y3] | ['h']
+type BarcodeType = 'datamatrix' | 'code128'
+interface BarcodeOptions { gs1?: boolean /* "(01)...(17)..." */; color?: string }
+renderBarcodeImage(type, text, opts?: BarcodeOptions & { module?: number }): string   // "data:image/svg+xml,..." for Image / Icon; on white, quiet zone included
+// Data Matrix ECC200 10x10..26x26 (44 chars, 88 digits, Latin-1); Code 128 ASCII. Too long or not encodable: throws.
+measureText(str: string, size: number, bold?: boolean): number   // Helvetica
+// Text: Helvetica, Windows-1252 (é € … ’); another character comes out as '?'. Printed at its size (PrintScaling /None).
 ```
 
 ---
@@ -1656,7 +1819,7 @@ Optional keys: `external`, `define`, `esbuild`, `dev` (`host`, `port`, `https`,
 - 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.
+- `enable(false)` / `disable()` put `disabled` and `inert` on the component itself. Its children are not changed: the browser makes all that is inside an `inert` element inactive (no click, no focus).
 - `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.
 - `BtnGroup` accepts predefined strings (`"ok"`, `"cancel"`...) with options after a dot: `"ok.outline.default.disabled"`.
@@ -1666,4 +1829,5 @@ Optional keys: `external`, `define`, `esbuild`, `dev` (`host`, `port`, `https`,
 - `DataRecordID` is currently typed `any`; `strictNullChecks` is intentionally off in the recommended `tsconfig.json`.
 - `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.
+- A DOM handler of an ancestor is called for the events of its descendants, as in the browser. Not for the events that do not bubble: `focus`, `blur`, `mouseenter`, `mouseleave` (use `focusin` / `focusout`, `mouseover` / `mouseout`), nor for those of x4: `created`, `removed`, `resized`.
+- Several handlers of one event on one node are called in the order they were added. One that returns `true` stops those that follow it.

package/cli/config.mjs

@@ -92,16 +92,20 @@ function readJson(filename) {
     }
 }
 
-function validateCopy(copy) {
+function validateCopy(copy, env) {
     if (!Array.isArray(copy))
         throw new Error("copy must be an array");
 
     for (const item of copy) {
         if (!item || typeof item !== "object" || typeof item.from !== "string" || typeof item.to !== "string")
             throw new Error("Each copy entry must contain string 'from' and 'to' fields");
-        if (path.isAbsolute(item.to))
+
+        // checked once expanded: a $NAME could hold "..".
+        // A root: "D:assets" is not absolute, but goes to the folder of D:
+        const to = expandEnv(item.to, env);
+        if (path.isAbsolute(to) || path.parse(to).root)
             throw new Error(`copy destination must be relative to outdir: '${item.to}'`);
-        const normalized = path.normalize(item.to);
+        const normalized = path.normalize(to);
         if (normalized === ".." || normalized.startsWith(`..${path.sep}`))
             throw new Error(`copy destination escapes outdir: '${item.to}'`);
     }
@@ -125,7 +129,7 @@ export function loadConfig(root = process.cwd(), configFile = DEFAULT_CONFIG_FIL
         throw new Error("entryPoints must be a non-empty array of strings");
 
     const copy = cfg.copy ?? DEFAULTS.copy;
-    validateCopy(copy);
+    validateCopy(copy, env);
 
     const external = cfg.external ?? DEFAULTS.external;
     if (!Array.isArray(external) || external.some((entry) => typeof entry !== "string"))
@@ -165,11 +169,14 @@ export function loadConfig(root = process.cwd(), configFile = DEFAULT_CONFIG_FIL
         throw new Error("outdir must be a string");
 
     const outdir = resolvePath(root, outdirRaw, env);
-    if (outdir === root)
-        throw new Error("outdir cannot be the project root");
     if (outdir === path.parse(outdir).root)
         throw new Error("outdir cannot be a filesystem root");
 
+    // the output folder is emptied before each build: it must not be the project, nor a folder that holds it
+    const fromOutdir = path.relative(outdir, root);
+    if (fromOutdir !== ".." && !fromOutdir.startsWith(`..${path.sep}`) && !path.isAbsolute(fromOutdir))
+        throw new Error(`outdir cannot be the project root, nor a folder that contains it: '${outdir}'`);
+
     let esbuildOptions = {};
     if (cfg.esbuild !== undefined) {
         if (!cfg.esbuild || typeof cfg.esbuild !== "object" || Array.isArray(cfg.esbuild))
@@ -184,7 +191,7 @@ export function loadConfig(root = process.cwd(), configFile = DEFAULT_CONFIG_FIL
         outdir,
         copy: copy.map((item) => ({
             from: resolvePath(root, item.from, env),
-            to: path.normalize(item.to),
+            to: path.normalize(expandEnv(item.to, env)),
         })),
         external: [...external],
         define: Object.fromEntries(

package/cli/copy-plugin.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { warning } from "./log.mjs";
 
 async function walk(source) {
     const files = [];
@@ -51,6 +52,13 @@ export function copyPlugin(config, { dev = false } = {}) {
         for (const entry of entries) {
             const result = await walk(entry.from);
             entry.sourceIsDirectory = result.isDirectory;
+
+            // its folder is watched: in dev, its creation starts a build
+            if (!result.files.length && !result.isDirectory) {
+                warning(`copy: not found: ${entry.from}`);
+                dirs.push(path.dirname(entry.from));
+            }
+
             dirs.push(...result.dirs);
             for (const item of result.files) {
                 files.push({ entry, ...item });

package/cli/create.mjs

@@ -127,8 +127,10 @@ export async function create(argv = [], { version = "unknown", cwd = process.cwd
     try {
         const files = await fetchTemplateFiles(values.template, version);
 
-        await Promise.all(files.map(async (file) => {
-            if (!file.path || file.path.split("/").includes(".."))
+        // a \ is a separator on Windows: "..\x" would go out of the target
+        // allSettled: every write is over before the cleanup of the catch
+        const results = await Promise.allSettled(files.map(async (file) => {
+            if (!file.path || file.path.includes("\\") || file.path.split("/").includes(".."))
                 throw new Error(`Unsafe template path '${file.path}'`);
             const destination = path.join(target, ...file.path.split("/"));
             await fs.mkdir(path.dirname(destination), { recursive: true });
@@ -136,6 +138,10 @@ export async function create(argv = [], { version = "unknown", cwd = process.cwd
             await fs.writeFile(destination, data);
         }));
 
+        const failed = results.find((result) => result.status === "rejected");
+        if (failed)
+            throw failed.reason;
+
         await patchPackage(target, projectName, version);
         projectReady = true;