x4js 2.3.12 → 2.3.14

package/aicli.md

@@ -5,8 +5,8 @@
 ```
 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 dev   [--config <file>] [--env <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
+x4js build [--config <file>] [--env <file>] [--debug]
 x4js --help | --version
 ```
 
@@ -76,6 +76,7 @@ Builds the application, serves the output folder and rebuilds on every change.
 | Option | Effect |
 |---|---|
 | `--config <file>` | Config file to use. Default: `x4.config.json`. |
+| `--env <file>` | File of variables for `$NAME` in the config (see below). |
 | `--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. |
@@ -83,7 +84,7 @@ Builds the application, serves the output folder and rebuilds on every change.
 
 - 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.
+- Editing the config file restarts the build. The file given to `--env` is read again at that moment; editing it alone restarts nothing.
 - HTTPS needs a certificate and a key, declared in `dev.tls` (see below).
 
 ### `x4js build`
@@ -93,6 +94,7 @@ Writes the application to the output folder.
 | Option | Effect |
 |---|---|
 | `--config <file>` | Config file to use. Default: `x4.config.json`. |
+| `--env <file>` | File of variables for `$NAME` in the config (see below). |
 | `--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`.
@@ -129,7 +131,60 @@ The file sits at the root of the project. Every key is optional; without the fil
 | `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.
+Relative paths are resolved from the project root. Paths and `define` values accept environment variables, written `$NAME` or `${NAME}`; an undefined variable is an error.
+
+### Environment variables in `define`
+
+A `define` value is a JavaScript expression, so a text is written between escaped double quotes. The variable is read when the command runs: its value ends up in the bundle.
+
+```json
+{
+	"define": {
+		"API_URL": "\"$API_URL\"",
+		"API_PORT": "$API_PORT"
+	}
+}
+```
+
+```ts
+declare const API_URL: string;
+declare const API_PORT: number;
+```
+
+With `API_URL=https://example.com` and `API_PORT=8080`, the code sees the text `"https://example.com"` and the number `8080`. A quote or a backslash in the value of a variable is escaped: use double quotes around `$NAME`, not single ones.
+
+Everything in the bundle is public: do not put a secret in `define`.
+
+### Variables from a file
+
+`--env <file>` reads variables from a file of `NAME=value` lines, for `dev` and `build`:
+
+```
+# .env
+API_URL=https://example.com
+API_PORT=8080
+```
+
+```
+x4js dev --env .env
+```
+
+- The file only serves `$NAME` in the config. Its variables are not given to the application: pass the ones it needs through `define`.
+- A variable already defined in the environment keeps its value: the file only adds the missing ones.
+- A file that does not exist is an error.
+
+This lets the same config work on a machine and on a host that defines the variables itself:
+
+```json
+{
+	"scripts": {
+		"dev": "x4js dev --env .env",
+		"build": "x4js build"
+	}
+}
+```
+
+Keep the file out of Git when it holds values that are not public.
 
 ### The HTML page
 
@@ -189,6 +244,7 @@ declare const VERSION_ID: number;
 | 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. |
+| `Environment variable '…' is not defined` | A path or a `define` value in the config uses `$NAME` and the variable is not set, in the environment or in the file given to `--env`. |
+| `Env file not found` | The file given to `--env` does not exist. |
 | `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

@@ -130,7 +130,7 @@ interface ComponentProps {
   ns?: string                                        // SVG/MathML namespace
   cls?: string                                       // extra CSS classes
   id?: string
-  style?: Partial<CSSStyleDeclaration>
+  style?: StyleProps                                 // numbers get "px" except unitless
   attrs?: Record<string, string | number | boolean>
   content?: ComponentContent
   dom_events?: GlobalDOMEvents
@@ -188,7 +188,7 @@ getInternalData<T>(name: string|symbol): T
 ### Styles
 
 ```ts
-setStyle(style: Partial<CSSStyleDeclaration>): this  // numbers auto-suffixed "px" except unitless
+setStyle(style: StyleProps): this  // numbers auto-suffixed "px" except unitless
 setStyleValue<K>(name: K, value): this
 getStyleValue<K>(name: K): CSSStyleDeclaration[K]
 setWidth(w: number|string): void
@@ -633,7 +633,20 @@ class AutoComplete extends TextEdit {
 ### `ColorInput`
 
 ```ts
-class ColorInput extends HBox {}           // queryInterface("form-element")
+interface ColorInputProps extends BoxProps {
+  color: Color | string                    // null: no color shown
+  name?: string
+  format?: "rgb" | "hex"                   // text of the field, "rgb" by default
+  picker?: boolean                         // a click on the swatch opens a ColorPicker
+  swatches?: (Color|string)[] | (() => (Color|string)[])   // a function is called each time the picker opens
+  nullable?: boolean                       // "no color" can be chosen
+  change?: EventCallback<EvColorChange>    // user changes only, not setColor
+}
+class ColorInput extends HBox {            // queryInterface("form-element"): "#rrggbb" or null
+  getColor(): Color; getValue(): string
+  setColor(color: Color | string): void; setSwatches(swatches): void
+}
+interface EvColorChange extends EvChange { color: Color; value: string }  // "#rrggbb" or "#rrggbbaa"; both null for "no color"
 ```
 
 ### `FileDrop` / `FileDialog`
@@ -796,6 +809,9 @@ class PropertyGrid extends VBox {
   setItems(groups: PropertyGroup[]): void
   setPropValue(name: string, value): void
 }
+// PropertyValue.type: 'boolean' | 'number' | 'string' | 'password' | 'options' | 'color' | 'label' | 'button'
+// 'color': the editor is a ColorInput (hex, with picker); swatches?: string[] | (() => string[]), nullable?: boolean,
+//          callback(name, value) receives "#rrggbb", or null for "no color"
 ```
 
 ---
@@ -978,7 +994,9 @@ class Video extends Box {
   set stream(stream: MediaStream)
 }
 class Calendar extends VBox { getDate(): Date; setDate(date: Date): void }
-class ColorPicker extends VBox             // queryInterface("form-element")
+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

package/cli/build-options.mjs

@@ -27,12 +27,12 @@ export function createBuildOptions(config, mode) {
         charset: "utf8",
         keepNames: true,
         platform: "browser",
-		logLevel: "silent",
+        // Errors and warnings are printed by diagnostic-plugin.mjs.
+        logLevel: "silent",
         format: "iife",
         target: "es2020",
         minify: production,
         sourcemap: production ? false : "linked",
-        logLevel: "info",
         external: config.external,
         assetNames: "assets/[name]-[hash]",
         loader: {

package/cli/build.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import { parseArgs } from "node:util";
 import esbuild from "esbuild";
-import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig } from "./config.mjs";
+import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, loadEnvFile } from "./config.mjs";
 import { createBuildOptions } from "./build-options.mjs";
 import { info, success } from "./log.mjs";
 import { printBuildError, printWarnings } from "./diagnostic-plugin.mjs";
@@ -11,6 +11,7 @@ export async function build(argv = [], root = process.cwd()) {
         args: argv,
         options: {
             config: { type: "string" },
+            env: { type: "string" },
             debug: { type: "boolean", default: false },
         },
         allowPositionals: true,
@@ -20,12 +21,17 @@ export async function build(argv = [], root = process.cwd()) {
     if (positionals.length)
         throw new Error(`Unexpected argument: ${positionals[0]}`);
 
+    const envFile = values.env ? loadEnvFile(root, values.env) : undefined;
+    const env = envFile?.env ?? process.env;
+
     const configArg = values.config ? expandEnv(values.config) : DEFAULT_CONFIG_FILE;
-    const config = loadConfig(root, configArg, process.env, { explicit: values.config !== undefined });
+    const config = loadConfig(root, configArg, env, { explicit: values.config !== undefined });
     const mode = values.debug ? "debug" : "production";
 
     info("mode", mode);
     info("config", config.configFile);
+    if (envFile)
+        info("env file", envFile.filename);
     info("outdir", config.outdir);
 
     await fs.rm(config.outdir, { recursive: true, force: true });

package/cli/config.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { parseEnv } from "node:util";
 
 export const DEFAULT_CONFIG_FILE = "x4.config.json";
 
@@ -15,7 +16,7 @@ const DEFAULTS = Object.freeze({
     },
 });
 
-export function expandEnv(value, env = process.env) {
+export function expandEnv(value, env = process.env, escape = (text) => text) {
     if (typeof value !== "string")
         return value;
 
@@ -26,11 +27,18 @@ export function expandEnv(value, env = process.env) {
             const result = env[name];
             if (result === undefined)
                 throw new Error(`Environment variable '${name}' is not defined`);
-            return result;
+            return escape(result);
         },
     );
 }
 
+// A define value is a JavaScript expression, usually a string literal
+// ("\"$NAME\""). The value of the variable is escaped so that a quote or a
+// backslash in it cannot end or corrupt that literal.
+function escapeForDefine(text) {
+    return JSON.stringify(text).slice(1, -1);
+}
+
 export function resolvePath(root, value, env = process.env) {
     const expanded = expandEnv(value, env);
     return path.isAbsolute(expanded)
@@ -42,6 +50,39 @@ export function resolveConfigFile(root, configFile = DEFAULT_CONFIG_FILE, env =
     return resolvePath(root, configFile, env);
 }
 
+/**
+ * Reads the file given to --env.
+ * Returns the environment to expand the config with: the variables of the
+ * file, under those already defined, which win as with `node --env-file`.
+ *
+ * The option is not named --env-file on purpose: node handles that name
+ * itself, even after the script name, before this code runs.
+ */
+export function loadEnvFile(root, file, env = process.env) {
+    const filename = resolvePath(root, file, env);
+
+    let variables;
+    try {
+        variables = parseEnv(fs.readFileSync(filename, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error(`Env file not found: ${filename}`);
+        throw new Error(`Cannot read env file '${filename}': ${error.message}`);
+    }
+
+    // Inherit from the environment instead of copying it: process.env has
+    // its own lookup rules (names are case-insensitive on Windows).
+    // defineProperty, because a plain assignment would go through to it.
+    const merged = Object.create(env);
+    for (const [name, value] of Object.entries(variables)) {
+        if (env[name] === undefined)
+            Object.defineProperty(merged, name, { value, enumerable: true });
+    }
+
+    return { filename, env: merged };
+}
+
 function readJson(filename) {
     try {
         return JSON.parse(fs.readFileSync(filename, "utf8"));
@@ -146,7 +187,9 @@ export function loadConfig(root = process.cwd(), configFile = DEFAULT_CONFIG_FIL
             to: path.normalize(item.to),
         })),
         external: [...external],
-        define: { ...define },
+        define: Object.fromEntries(
+            Object.entries(define).map(([name, value]) => [name, expandEnv(value, env, escapeForDefine)]),
+        ),
         dev: {
             host,
             port,

package/cli/dev.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import esbuild from "esbuild";
-import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, resolveConfigFile, resolveTls } from "./config.mjs";
+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";
 
@@ -60,6 +60,7 @@ export async function dev(argv = [], root = process.cwd()) {
         args: argv,
         options: {
             config: { type: "string" },
+            env: { type: "string" },
             host: { type: "string" },
             port: { type: "string" },
             http: { type: "boolean", default: false },
@@ -86,7 +87,16 @@ export async function dev(argv = [], root = process.cwd()) {
     let restartChain = Promise.resolve();
     let browserOpened = false;
 
-    async function start(config) {
+    // Read again on each (re)start, so an edited env file is taken into
+    // account when the config is reloaded.
+    function load() {
+        const envFile = values.env ? loadEnvFile(root, values.env) : undefined;
+        const env = envFile?.env ?? process.env;
+        const config = loadConfig(root, configArg, env, { explicit: explicitConfig });
+        return { config, env, envFile };
+    }
+
+    async function start({ config, env, envFile }) {
         const host = values.host ?? config.dev.host;
         const port = values.port === undefined ? config.dev.port : Number(values.port);
         if (port !== undefined && (port < 0 || port > 65535))
@@ -101,7 +111,7 @@ export async function dev(argv = [], root = process.cwd()) {
         if (port !== undefined)
             serveOptions.port = port;
         if (useHttps)
-            Object.assign(serveOptions, resolveTls(config));
+            Object.assign(serveOptions, resolveTls(config, env));
 
         const next = await esbuild.context(createBuildOptions(config, "dev"));
         try {
@@ -113,6 +123,8 @@ export async function dev(argv = [], root = process.cwd()) {
             const url = serverUrl(actualHost, result.port, useHttps);
             info("mode", "dev");
             info("config", config.configFile);
+            if (envFile)
+                info("env file", envFile.filename);
             info("outdir", config.outdir);
             success("server", url);
 
@@ -128,12 +140,12 @@ export async function dev(argv = [], root = process.cwd()) {
     }
 
     async function reload() {
-        let config;
+        let loaded;
         try {
-            config = loadConfig(root, configArg, process.env, { explicit: explicitConfig });
-            protocolConfig(config, values);
-            if (values.https || (!values.http && config.dev.https))
-                resolveTls(config);
+            loaded = load();
+            protocolConfig(loaded.config, values);
+            if (values.https || (!values.http && loaded.config.dev.https))
+                resolveTls(loaded.config, loaded.env);
         }
         catch (error) {
             failure(`config: ${error.message}`);
@@ -146,7 +158,7 @@ export async function dev(argv = [], root = process.cwd()) {
             await previous.dispose();
 
         try {
-            await start(config);
+            await start(loaded);
             success("config", "reloaded");
         }
         catch (error) {
@@ -161,8 +173,7 @@ export async function dev(argv = [], root = process.cwd()) {
         }, 150);
     }
 
-    const initialConfig = loadConfig(root, configArg, process.env, { explicit: explicitConfig });
-    await start(initialConfig);
+    await start(load());
 
     const watchDir = path.dirname(watchedConfigFile);
     const watchName = path.basename(watchedConfigFile);

package/cli/main.mjs

@@ -21,11 +21,12 @@ function printHelp(version) {
 Usage:
   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 dev [--config <file>] [--env <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
+  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`);
 }

package/package.json

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

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

@@ -17,7 +17,8 @@
 :root {
 	--colorinput-btn-background: inherit;
 	--colorinput-btn-color: var( --text-secondary );
-	--colorinput-btn-color-hover: var( --text-primary );	
+	--colorinput-btn-color-hover: var( --text-primary );
+	--colorinput-popup-background: var( --background-primary );
 }
 
 .x4colorinput {
@@ -33,6 +34,27 @@
 		margin: 4px;
 		width: 1rem;
 		height: 1rem;
+
+		// props.picker: a click opens the color picker. It is a button:
+		// wide enough to be aimed at.
+		&.picker {
+			flex-shrink: 0;
+			width: 2.4rem;
+			height: 1.4rem;
+			border: 1px solid var( --border );
+			border-radius: 3px;
+			cursor: pointer;
+
+			&:hover {
+				border-color: var( --border-focus );
+			}
+		}
+
+		// props.nullable, no color: crossed out
+		&.none {
+			border: 1px solid var( --border );
+			background: linear-gradient( to top right, transparent 45%, #d04040 45%, #d04040 55%, transparent 55% );
+		}
 	}
 
 	input {
@@ -42,14 +64,19 @@
 		flex-grow: 1;
 	}
 
+	// the eye dropper: as high as the field, and wide enough to be aimed at
 	.x4button {
+		flex-shrink: 0;
+		align-self: stretch;
 		margin: 0;
-		padding: 0;
+		padding: 0 6px;
 		outline: none;
 		background-color: var( --combobox-btn-background );
 		color: var( --colorinput-btn-color );
 
 		#icon {
+			width: 1.3em;
+			height: 1.3em;
 			color: var( --colorinput-btn-color );
 		}
 
@@ -62,4 +89,11 @@
 			//color: var( --color-10 );
 		}
 	}
+}
+
+// the color picker opened from the swatch (props.picker)
+.x4colorinput-popup {
+	background-color: var( --colorinput-popup-background );
+	border: 1px solid var( --border );
+	box-shadow: 0 4px 12px rgba( 0, 0, 0, 0.3 );
 }