x4js 2.3.6 → 2.3.8

package/cli/build-options.mjs

@@ -4,7 +4,7 @@ import { sassPlugin } from "esbuild-sass-plugin";
 import { lessPlugin } from "./less-plugin.mjs";
 import { copyPlugin } from "./copy-plugin.mjs";
 import { rawFilePlugin } from "./rawfile-plugin.mjs";
-import { diagnosticsPlugin } from "./diagnostic.mjs";
+import { diagnosticsPlugin } from "./diagnostic-plugin.mjs";
 
 const cliDir = path.dirname(fileURLToPath(import.meta.url));
 const devClient = path.join(cliDir, "dev-client.js");

package/cli/build.mjs

@@ -1,15 +1,16 @@
 import fs from "node:fs/promises";
 import { parseArgs } from "node:util";
 import esbuild from "esbuild";
-import { loadConfig } from "./config.mjs";
+import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig } from "./config.mjs";
 import { createBuildOptions } from "./build-options.mjs";
 import { info, success } from "./log.mjs";
-import { printBuildError} from "./diagnostic-plugin.mjs";
+import { printBuildError, printWarnings } from "./diagnostic-plugin.mjs";
 
 export async function build(argv = [], root = process.cwd()) {
     const { values, positionals } = parseArgs({
         args: argv,
         options: {
+            config: { type: "string" },
             debug: { type: "boolean", default: false },
         },
         allowPositionals: true,
@@ -19,29 +20,26 @@ export async function build(argv = [], root = process.cwd()) {
     if (positionals.length)
         throw new Error(`Unexpected argument: ${positionals[0]}`);
 
-    const config = loadConfig(root);
+    const configArg = values.config ? expandEnv(values.config) : DEFAULT_CONFIG_FILE;
+    const config = loadConfig(root, configArg, process.env, { explicit: values.config !== undefined });
     const mode = values.debug ? "debug" : "production";
 
     info("mode", mode);
+    info("config", config.configFile);
     info("outdir", config.outdir);
 
     await fs.rm(config.outdir, { recursive: true, force: true });
     await fs.mkdir(config.outdir, { recursive: true });
 
     const started = performance.now();
-	const options = createBuildOptions(config, mode);
-
-	try {
-		const result = await esbuild.build(options);
-		if (result.warnings.length)
-			await printWarnings(result.warnings);
-
-		logSuccess(`built      ${Date.now() - start}ms`);
-	}
-	catch (error) {
-		await printBuildError(error);
-		process.exitCode = 1;
-	}
-
-	success("built", `${Math.round(performance.now() - started)}ms`);
+    try {
+        const result = await esbuild.build(createBuildOptions(config, mode));
+        if (result.warnings.length)
+            await printWarnings(result.warnings);
+        success("built", `${Math.round(performance.now() - started)}ms`);
+    }
+    catch (error) {
+        await printBuildError(error);
+        process.exitCode = 1;
+    }
 }

package/cli/config.mjs

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
+export const DEFAULT_CONFIG_FILE = "x4.config.json";
+
 const DEFAULTS = Object.freeze({
     entryPoints: ["src/main.ts"],
     outdir: "./bin",
@@ -36,94 +38,107 @@ export function resolvePath(root, value, env = process.env) {
         : path.resolve(root, expanded);
 }
 
+export function resolveConfigFile(root, configFile = DEFAULT_CONFIG_FILE, env = process.env) {
+    return resolvePath(root, configFile, env);
+}
+
+function readJson(filename) {
+    try {
+        return JSON.parse(fs.readFileSync(filename, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read config '${filename}': ${error.message}`);
+    }
+}
+
 function validateCopy(copy) {
     if (!Array.isArray(copy))
-        throw new Error("x4.copy must be an array");
+        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 x4.copy entry must contain string 'from' and 'to' fields");
+            throw new Error("Each copy entry must contain string 'from' and 'to' fields");
         if (path.isAbsolute(item.to))
-            throw new Error(`x4.copy destination must be relative to outdir: '${item.to}'`);
+            throw new Error(`copy destination must be relative to outdir: '${item.to}'`);
         const normalized = path.normalize(item.to);
         if (normalized === ".." || normalized.startsWith(`..${path.sep}`))
-            throw new Error(`x4.copy destination escapes outdir: '${item.to}'`);
+            throw new Error(`copy destination escapes outdir: '${item.to}'`);
     }
 }
 
-export function loadConfig(root = process.cwd(), env = process.env) {
+export function loadConfig(root = process.cwd(), configFile = DEFAULT_CONFIG_FILE, env = process.env, { explicit = false } = {}) {
     root = path.resolve(root);
-    const packageFile = path.join(root, "package.json");
-
-    if (!fs.existsSync(packageFile))
-        throw new Error(`Cannot find package.json in '${root}'`);
+    const filename = resolveConfigFile(root, configFile, env);
 
-    let pkg;
-    try {
-        pkg = JSON.parse(fs.readFileSync(packageFile, "utf8"));
-    }
-    catch (error) {
-        throw new Error(`Cannot read package.json: ${error.message}`);
-    }
+    let cfg = {};
+    if (fs.existsSync(filename))
+        cfg = readJson(filename);
+    else if (explicit)
+        throw new Error(`Config file not found: ${filename}`);
 
-    const cfg = pkg.x4 ?? {};
-    if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg))
-        throw new Error("package.json field 'x4' must be an object");
+    if (!cfg || typeof cfg !== "object" || Array.isArray(cfg))
+        throw new Error("x4 config must be an object");
 
     const entryPoints = cfg.entryPoints ?? DEFAULTS.entryPoints;
     if (!Array.isArray(entryPoints) || !entryPoints.length || entryPoints.some((entry) => typeof entry !== "string"))
-        throw new Error("x4.entryPoints must be a non-empty array of strings");
+        throw new Error("entryPoints must be a non-empty array of strings");
 
     const copy = cfg.copy ?? DEFAULTS.copy;
     validateCopy(copy);
 
     const external = cfg.external ?? DEFAULTS.external;
     if (!Array.isArray(external) || external.some((entry) => typeof entry !== "string"))
-        throw new Error("x4.external must be an array of strings");
+        throw new Error("external must be an array of strings");
 
     const define = cfg.define ?? DEFAULTS.define;
     if (!define || typeof define !== "object" || Array.isArray(define))
-        throw new Error("x4.define must be an object");
+        throw new Error("define must be an object");
     if (Object.values(define).some((value) => typeof value !== "string"))
-        throw new Error("x4.define values must be strings containing esbuild define expressions");
+        throw new Error("define values must be strings containing esbuild define expressions");
 
     const devCfg = cfg.dev ?? {};
     if (!devCfg || typeof devCfg !== "object" || Array.isArray(devCfg))
-        throw new Error("x4.dev must be an object");
+        throw new Error("dev must be an object");
 
     const host = devCfg.host ?? DEFAULTS.dev.host;
     if (typeof host !== "string" || !host)
-        throw new Error("x4.dev.host must be a non-empty string");
+        throw new Error("dev.host must be a non-empty string");
 
     const port = devCfg.port;
     if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535))
-        throw new Error("x4.dev.port must be an integer between 0 and 65535");
+        throw new Error("dev.port must be an integer between 0 and 65535");
 
     const https = devCfg.https ?? DEFAULTS.dev.https;
     if (typeof https !== "boolean")
-        throw new Error("x4.dev.https must be a boolean");
+        throw new Error("dev.https must be a boolean");
 
     if (devCfg.tls !== undefined) {
         if (!devCfg.tls || typeof devCfg.tls !== "object" || Array.isArray(devCfg.tls))
-            throw new Error("x4.dev.tls must be an object");
+            throw new Error("dev.tls must be an object");
         if (typeof devCfg.tls.cert !== "string" || typeof devCfg.tls.key !== "string")
-            throw new Error("x4.dev.tls requires string 'cert' and 'key' fields");
+            throw new Error("dev.tls requires string 'cert' and 'key' fields");
     }
 
     const outdirRaw = cfg.outdir ?? DEFAULTS.outdir;
     if (typeof outdirRaw !== "string")
-        throw new Error("x4.outdir must be a string");
+        throw new Error("outdir must be a string");
 
     const outdir = resolvePath(root, outdirRaw, env);
     if (outdir === root)
-        throw new Error("x4.outdir cannot be the project root");
+        throw new Error("outdir cannot be the project root");
     if (outdir === path.parse(outdir).root)
-        throw new Error("x4.outdir cannot be a filesystem root");
+        throw new Error("outdir cannot be a filesystem root");
+
+    let esbuildOptions = {};
+    if (cfg.esbuild !== undefined) {
+        if (!cfg.esbuild || typeof cfg.esbuild !== "object" || Array.isArray(cfg.esbuild))
+            throw new Error("esbuild must be an object");
+        esbuildOptions = { ...cfg.esbuild };
+    }
 
     return {
         root,
-        packageFile,
-        package: pkg,
+        configFile: filename,
         entryPoints: entryPoints.map((entry) => resolvePath(root, entry, env)),
         outdir,
         copy: copy.map((item) => ({
@@ -132,26 +147,20 @@ export function loadConfig(root = process.cwd(), env = process.env) {
         })),
         external: [...external],
         define: { ...define },
-		dev: {
+        dev: {
             host,
             port,
             https,
             tls: devCfg.tls ? { ...devCfg.tls } : undefined,
         },
-        esbuild: (() => {
-            if (cfg.esbuild === undefined)
-                return {};
-            if (!cfg.esbuild || typeof cfg.esbuild !== "object" || Array.isArray(cfg.esbuild))
-                throw new Error("x4.esbuild must be an object");
-            return { ...cfg.esbuild };
-        })(),
+        esbuild: esbuildOptions,
     };
 }
 
 export function resolveTls(config, env = process.env) {
     const tls = config.dev.tls;
     if (!tls)
-        throw new Error("HTTPS is enabled but x4.dev.tls.cert/key are not configured");
+        throw new Error("HTTPS is enabled but dev.tls.cert/key are not configured");
 
     const certfile = resolvePath(config.root, tls.cert, env);
     const keyfile = resolvePath(config.root, tls.key, env);

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 { loadConfig, resolveTls } from "./config.mjs";
+import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, resolveConfigFile, resolveTls } from "./config.mjs";
 import { createBuildOptions } from "./build-options.mjs";
 import { info, success, failure } from "./log.mjs";
 
@@ -59,6 +59,7 @@ export async function dev(argv = [], root = process.cwd()) {
     const { values, positionals } = parseArgs({
         args: argv,
         options: {
+            config: { type: "string" },
             host: { type: "string" },
             port: { type: "string" },
             http: { type: "boolean", default: false },
@@ -71,12 +72,15 @@ export async function dev(argv = [], root = process.cwd()) {
 
     if (positionals.length)
         throw new Error(`Unexpected argument: ${positionals[0]}`);
-
     if (values.port !== undefined && !/^\d+$/.test(values.port))
         throw new Error("--port must be an integer");
 
+    const configArg = values.config ? expandEnv(values.config) : DEFAULT_CONFIG_FILE;
+    const explicitConfig = values.config !== undefined;
+    const watchedConfigFile = resolveConfigFile(root, configArg);
+
     let context;
-    let packageWatcher;
+    let configWatcher;
     let stopping = false;
     let restartTimer;
     let restartChain = Promise.resolve();
@@ -96,7 +100,6 @@ export async function dev(argv = [], root = process.cwd()) {
 
         if (port !== undefined)
             serveOptions.port = port;
-
         if (useHttps)
             Object.assign(serveOptions, resolveTls(config));
 
@@ -109,6 +112,7 @@ export async function dev(argv = [], root = process.cwd()) {
             const actualHost = result.hosts.includes(host) ? host : (result.hosts[0] ?? host);
             const url = serverUrl(actualHost, result.port, useHttps);
             info("mode", "dev");
+            info("config", config.configFile);
             info("outdir", config.outdir);
             success("server", url);
 
@@ -126,9 +130,9 @@ export async function dev(argv = [], root = process.cwd()) {
     async function reload() {
         let config;
         try {
-            config = loadConfig(root);
+            config = loadConfig(root, configArg, process.env, { explicit: explicitConfig });
             protocolConfig(config, values);
-            if ((values.https || (!values.http && config.dev.https)))
+            if (values.https || (!values.http && config.dev.https))
                 resolveTls(config);
         }
         catch (error) {
@@ -147,8 +151,6 @@ export async function dev(argv = [], root = process.cwd()) {
         }
         catch (error) {
             failure(`restart: ${error.message}`);
-            // The old context cannot be restored after dispose. Keep watching
-            // package.json so fixing the configuration starts dev again.
         }
     }
 
@@ -159,11 +161,13 @@ export async function dev(argv = [], root = process.cwd()) {
         }, 150);
     }
 
-    const initialConfig = loadConfig(root);
+    const initialConfig = loadConfig(root, configArg, process.env, { explicit: explicitConfig });
     await start(initialConfig);
 
-    packageWatcher = fs.watch(path.resolve(root), { persistent: true }, (_event, filename) => {
-        if (filename === null || filename.toString() === "package.json")
+    const watchDir = path.dirname(watchedConfigFile);
+    const watchName = path.basename(watchedConfigFile);
+    configWatcher = fs.watch(watchDir, { persistent: true }, (_event, filename) => {
+        if (filename === null || filename.toString() === watchName)
             scheduleReload();
     });
 
@@ -172,7 +176,7 @@ export async function dev(argv = [], root = process.cwd()) {
             return;
         stopping = true;
         clearTimeout(restartTimer);
-        packageWatcher?.close();
+        configWatcher?.close();
         await restartChain.catch(() => {});
         await context?.dispose();
     }

package/cli/main.mjs

@@ -21,10 +21,11 @@ function printHelp(version) {
 Usage:
   x4js create <project> [--template <name>] [--no-install]
   x4js templates
-  x4js dev [--host <host>] [--port <port>] [--http|--https] [--open]
-  x4js build [--debug]
+  x4js dev [--config <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
+  x4js build [--config <file>] [--debug]
 
 Options:
+  --config <file>  Config file (default: x4.config.json)
   -h, --help       Show help
   -v, --version    Show version`);
 }

package/package.json

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

package/src/core/component.ts

@@ -22,10 +22,6 @@ import { addEvent, DOMEventHandler, GlobalDOMEvents, COMPONENT } from './core_do
 import { Application, EvMessage } from './core_application';
 import { makeState } from './core_state.js';
 
-interface RefType<T extends Component> {
-	dom: T;
-}
-
 type ComponentAttributes = Record<string,string|number|boolean>;
 type CreateComponentCallBack =  ( attrs: Record<string,string> ) => ComponentContent;
 
@@ -95,8 +91,6 @@ export interface ComponentProps {
     cls?: string;
 	/** Element ID. */
     id?: string;
-	/** Reference to the component instance. */
-    ref?: RefType<any>;
 	
 	// shortcuts
 	/** Width (px or string like `"50%"` or `"3em"`). */
@@ -628,7 +622,7 @@ export class Component<P extends ComponentProps = ComponentProps, E extends Comp
 				set( child );
 			}
 
-			d.insertBefore( d.firstChild, fragment );
+			d.insertBefore( fragment, d.firstChild );
 		}
 	}
 

package/src/core/core_element.ts

@@ -259,8 +259,10 @@ export class CoreElement<E extends EventMap = EventMap> {
 
 	cleanUp( ) {
 		this.clearTimeouts( );
-		this.#cleanup?.forEach( x => x() );
-		this.#cleanup.length = 0;
+		if( this.#cleanup ) {
+			this.#cleanup.forEach( x => x() );
+			this.#cleanup.length = 0;
+		}
 	}
 
 	// :: EVENTS ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

package/src/core/core_react.ts

@@ -46,32 +46,52 @@ import { Constructor, isString } from './core_tools';
 export class x4_react {
 
 	static create_element( tag: string, props: any, ...content: any[] ): Component;
-	static create_element<X extends Component>( tag: string | Constructor<X>, props: X["props"], ...content: any[] ) {
-		
-		props = props || {};
+	static create_element<X extends Component>( tag: string | Constructor<X>, props: X["props"], ...children: any[] ) {
+
+		// ref is a JSX-only attribute: never passed to the component
+		const { ref, ...attrs } = ( props ?? {} ) as any;
+
+		// flatten {items.map(...)} and drop null / false from conditional children
+		const content = children.flat( Infinity )
+								.filter( c => c !== null && c !== undefined && c !== false );
 
 		let el: Component;
 
-		// --- simple div ------------------------
-		if( isString(tag) ) {
+		// --- simple html element ------------------------
+		if( isString( tag ) ) {
 			el = new Component( { tag } );
-			Object.entries( props )
-				.forEach(([name, value]) => {
-					if (name.startsWith('on') && name.toLowerCase() in window) {
-						el.dom.addEventListener(name.toLowerCase().substring(2), value)
+
+			Object.entries( attrs )
+				.forEach( ( [name, value]: [string, any] ) => {
+					if( name.startsWith( 'on' ) && name.toLowerCase( ) in window ) {
+						el.dom.addEventListener( name.toLowerCase( ).substring( 2 ), value );
 					}
 					else {
-						el.setAttribute(name, value )
+						el.setAttribute( name, value );
 					}
 				});
+
+			if( content.length ) {
+				el.setContent( content );
+			}
 		}
 		// --- Component ------------------------
 		else {
-			el = new tag( props );
+			// same path as object construction: <X a={1}>{kids}</X> === new X({ a: 1, content: kids })
+			el = new tag( content.length ? { ...attrs, content } : attrs );
 		}
 
-		if( content && content.length ) {
-			el.appendContent( content );
+		// ref={[owner, "name"]} stores the element in owner.refs.name
+		if( ref ) {
+			const [owner, name] = ref;
+
+			// the owner must be a Box: only Box has refs
+			if( !owner?.refs || typeof name !== "string" ) {
+				console.error( "invalid JSX ref, expected [ownerBox, \"name\"]:", ref );
+			}
+			else {
+				owner.refs[name] = el;
+			}
 		}
 
 		return el;

package/src/x4tsx.d.ts

@@ -21,6 +21,10 @@ declare global {
 		interface IntrinsicElements {
 			[ name: string ]: any;
 		}
+
+		interface IntrinsicClassAttributes<T> {
+			ref?: [ owner: object, name: string ];
+		}
 	}
 }