x4js 2.3.18 → 2.3.20

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

@@ -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
@@ -577,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 {
@@ -598,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
@@ -631,6 +631,7 @@ 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
 }
@@ -641,7 +642,7 @@ class TextEdit extends HBox {
 ```ts
 interface SimpleTextAreaProps extends BaseProps {   // BaseProps: see Input (name, readonly, required, placeholder, autofocus, focus, change)
   value?: string
-  resize?: boolean | "none" | "vertical" | "horizontal" | "both"   // false = "none"
+  resize?: boolean | "none" | "vertical" | "horizontal" | "both"   // no handle by default; true = "both", false = "none"
   trim?: boolean                           // getText() trims, unless false
 }
 interface TextAreaProps extends SimpleTextAreaProps { label?: string }
@@ -675,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
@@ -695,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 {}
 ```
 
@@ -713,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
 }
 ```
 
@@ -746,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
 }
@@ -1083,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)
 }
 ```
 
@@ -1096,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>
@@ -1134,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").
 ```
@@ -1164,7 +1168,9 @@ 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
 }
@@ -1177,6 +1183,7 @@ class Keyboard extends HBox {               // virtual keyboard, shown while an
   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"
 ```
@@ -1237,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" }
@@ -1268,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 }
@@ -1455,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
@@ -1526,10 +1533,31 @@ 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
+  svgPath(d: string, x, y, scale, fill: string, stroke?: string, lineWidth?): void   // (x,y): the svg origin, its y going down; M L H V C S Q T A Z
+  icon(svg: string, x, y, w, h, opts?: { color?: string; background?: string }): void   // as Icon takes it (not a file); viewBox fitted in w x h; opacity mixed with background
+}
+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).
 ```
 
 ---

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;
 

package/cli/dev.mjs

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 import esbuild from "esbuild";
 import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, loadEnvFile, resolveConfigFile, resolveTls } from "./config.mjs";
 import { createBuildOptions } from "./build-options.mjs";
-import { info, success, failure } from "./log.mjs";
+import { info, success, failure, warning } from "./log.mjs";
 
 function openBrowser(url) {
     let command;
@@ -28,6 +28,9 @@ function openBrowser(url) {
         detached: true,
         stdio: "ignore",
     });
+
+    // no browser could be started (xdg-open missing...): the server goes on
+    child.on("error", (error) => warning(`cannot open the browser: ${error.message}`));
     child.unref();
 }
 

package/cli/less-plugin.mjs

@@ -28,7 +28,11 @@ export function lessPlugin(projectRoot) {
         setup(build) {
             build.onLoad({ filter: /\.less$/ }, async (args) => {
                 const source = await fs.readFile(args.path, "utf8");
-                lessPromise ??= loadLess(projectRoot);
+                // not kept when it fails: less can be installed while dev runs
+                lessPromise ??= loadLess(projectRoot).catch((error) => {
+                    lessPromise = undefined;
+                    throw error;
+                });
                 const less = await lessPromise;
 
                 const result = await less.render(source, {

package/cli/main.mjs

@@ -25,17 +25,27 @@ Usage:
   x4js build [--config <file>] [--env <file>] [--debug]
 
 Options:
-  --config <file>  Config file (default: x4.config.json)
-  --env <file>     File of NAME=value lines, for $NAME in the config
-  -h, --help       Show help
-  -v, --version    Show version`);
+  --config <file>          Config file (default: x4.config.json)
+  --env <file>             File of NAME=value lines, for $NAME in the config
+  -t, --template <name>    create: template to use (default: app)
+  --no-install             create: do not run npm install
+  --host <host>            dev: address to listen on (default: 127.0.0.1)
+  --port <port>            dev: port to listen on (default: the first free port from 8000)
+  --http, --https          dev: force the protocol, whatever the config says
+  --open                   dev: open the browser once the server is ready
+  --debug                  build: not minified, with source maps
+  -h, --help               Show help
+  -v, --version            Show version`);
 }
 
 const version = getVersion();
 const [command, ...argv] = process.argv.slice(2);
 
+// x4js <command> --help: the help, that gives the options of every command
+const help = argv.includes("--help") || argv.includes("-h");
+
 try {
-    switch (command) {
+    switch (help ? "help" : command) {
         case "create": {
             const { create } = await import("./create.mjs");
             await create(argv, { version });

package/cli/rawfile-plugin.mjs

@@ -8,15 +8,35 @@ export function rawFilePlugin({ filter, mime }) {
         name: "x4-raw-file",
 
         setup(build) {
-            build.onResolve({ filter }, (args) => {
+            build.onResolve({ filter }, async (args) => {
                 // Seulement les imports JS/TS.
+                // pluginData: the call of build.resolve below, which esbuild resolves itself
                 if (
-                    args.kind !== "import-statement" &&
-                    args.kind !== "dynamic-import"
+                    (args.kind !== "import-statement" &&
+                    args.kind !== "dynamic-import") ||
+                    args.pluginData === namespace
                 ) {
                     return;
                 }
 
+                // a package: esbuild finds it in node_modules. Its file is read here
+                // too, in base64: Icon inserts the svg of the url as it is, a "%23"
+                // of a url in text would stay in it
+                if (!args.path.startsWith(".") && !path.isAbsolute(args.path)) {
+                    const found = await build.resolve(args.path, {
+                        kind: args.kind,
+                        resolveDir: args.resolveDir,
+                        importer: args.importer,
+                        pluginData: namespace,
+                    });
+
+                    if (found.errors.length) {
+                        return { errors: found.errors };
+                    }
+
+                    return { path: found.path, namespace };
+                }
+
                 return {
                     path: path.resolve(args.resolveDir, args.path),
                     namespace,

package/cli/templates.mjs

@@ -1,7 +1,11 @@
+import { parseArgs } from "node:util";
 import { fetchTemplates } from "./templates-source.mjs";
 import { color } from "./log.mjs";
 
-export async function templates(_argv = [], { version = "unknown" } = {}) {
+export async function templates(argv = [], { version = "unknown" } = {}) {
+    // takes no argument: one given is an error
+    parseArgs({ args: argv, options: {}, strict: true });
+
     const manifest = await fetchTemplates(version);
     const names = Object.keys(manifest).sort();
     const width = names.reduce((max, name) => Math.max(max, name.length), 0) + 3;

package/package.json

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

package/src/components/calendar/calendar.module.scss

@@ -41,7 +41,10 @@
 .x4calendar {
 	border: 1px solid var( --border );
 	padding: 4px;
-	
+
+	// too short for its weeks (6 in some months): what does not fit is cut, not drawn over what follows
+	overflow: hidden;
+
 	.month-sel {
 		height: 2em;
 		align-items: center;
@@ -147,6 +150,18 @@
 				color: var( --calendard-day-color-hover );
 			}
 		}
+
+		// out of minDate..maxDate: cannot be chosen
+		.disabled {
+			color: var( --calendar-out-color );
+			text-decoration: line-through;
+			cursor: default;
+		}
+
+		.disabled:hover .text {
+			background-color: transparent;
+			color: var( --calendar-out-color );
+		}
 	}
 
 	.header {

package/src/components/calendar/calendar.ts

@@ -78,7 +78,7 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 		super(props);
 
 		this.mapPropEvents( props, 'change' );
-		this.m_date = props.date ? date_clone( props.date ) : new Date();
+		this.m_date = this._clamp( props.date ? date_clone( props.date ) : new Date() );
 
 		this._update( );
 	}
@@ -130,7 +130,7 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 				}),
 				new Flex( ),
 				new Button({ icon: icon_prev, click: () => this._next(false) } ),
-				new Button({ icon: icon_today, click: () => this.setDate(new Date()), tooltip: _tr.global.today } ),
+				new Button({ icon: icon_today, click: () => this.setDate( this._clamp( new Date() ) ), tooltip: _tr.global.today } ),
 				new Button({ icon: icon_next, click: () => this._next(true) } )
 			]
 		});
@@ -159,6 +159,9 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 		}));
 
 		let cmonth = this.m_date.getMonth();
+		const { minDate, maxDate } = this.props;
+		const min_hash = minDate ? date_hash( minDate ) : null;
+		const max_hash = maxDate ? date_hash( maxDate ) : null;
 
 		// weeks
 		let first = true;
@@ -184,6 +187,13 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 					cls += ' out';
 				}
 
+				// out of minDate..maxDate: shown, not chosen
+				const hash = date_hash( dte );
+				const off = (min_hash!==null && hash < min_hash) || (max_hash!==null && hash > max_hash);
+				if( off ) {
+					cls += ' disabled';
+				}
+
 				const mkItem = ( dte: Date ) => {
 					return new HBox({
 						cls,
@@ -192,7 +202,7 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 							cls: "text",
 							content: unsafeHtml( `<span>${formatIntlDate(dte, 'd')}</span>` ),
 						}),
-						dom_events: {
+						dom_events: off ? undefined : {
 							click: () => this.select(dte)
 						}
 					})
@@ -230,8 +240,40 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 	 */
 
 	private _next(n: boolean) {
-		this.m_date.setMonth(this.m_date.getMonth() + (n ? 1 : -1));
-		this._update();
+		this._goto( this.m_date.getFullYear( ), this.m_date.getMonth() + (n ? 1 : -1) );
+	}
+
+	/**
+	 * shows another month: the day is kept, not past the end of the month
+	 * (31 January → 28 February), and the date stays between minDate and maxDate
+	 */
+
+	private _goto( year: number, month: number ) {
+		const day = this.m_date.getDate( );
+		const d = date_clone( this.m_date );
+		d.setDate( 1 );
+		d.setFullYear( year, month );		// month 12: January of the next year
+		d.setDate( Math.min( day, new Date( d.getFullYear( ), d.getMonth( )+1, 0 ).getDate( ) ) );
+
+		this.m_date = this._clamp( d );
+		this._update( );
+	}
+
+	/**
+	 * the date brought between minDate and maxDate
+	 */
+
+	private _clamp( d: Date ) {
+		const { minDate, maxDate } = this.props;
+		if( minDate && d < minDate ) {
+			return date_clone( minDate );
+		}
+
+		if( maxDate && d > maxDate ) {
+			return date_clone( maxDate );
+		}
+
+		return d;
 	}
 
 	/**
@@ -246,7 +288,7 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 			for (let m = 0; m < 12; m++) {
 				items.push(({
 					text: _tr.global.month_long[m],
-					click: () => { this.m_date.setMonth(m); this._update(); }
+					click: () => { this._goto( this.m_date.getFullYear( ), m ); }
 				}));
 			}
 		}
@@ -258,7 +300,7 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 			for (let m = max; m >= min; m--) {
 				items.push({
 					text: '' + m,
-					click: () => { this.m_date.setFullYear(m); this._update(); }
+					click: () => { this._goto( m, this.m_date.getMonth( ) ); }
 				});
 			}
 		}
@@ -271,12 +313,13 @@ export class Calendar extends VBox<CalendarProps, CalendarEventMap>
 		menu.displayAt(rc.left, rc.top);
 	}
 
+	// a copy: the calendar and its caller do not share the object
 	getDate() {
-		return this.m_date;
+		return date_clone( this.m_date );
 	}
 
 	setDate(date: Date) {
-		this.m_date = date;
+		this.m_date = date_clone( date );
 		this._update();
 	}
 }

package/src/components/checkbox/checkbox.ts

@@ -71,6 +71,7 @@ export class Checkbox extends Component<CheckboxProps,CheckBoxEvents> {
 						type:"checkbox", 
 						id: inputId, 
 						name: props.name,
+						value: props.value,		// sent by a <form> of the browser when checked; a Form of x4 reads a boolean
 						checked: props.checked,
 						dom_events: {
 							change: ( ) => this._on_change( ),