x4js 2.2.73 → 2.3.1

package/cli/dev.mjs

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+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 { createBuildOptions } from "./build-options.mjs";
+import { info, success, failure } from "./log.mjs";
+
+function openBrowser(url) {
+    let command;
+    let args;
+
+    if (process.platform === "win32") {
+        command = "cmd";
+        args = ["/c", "start", "", url];
+    }
+    else if (process.platform === "darwin") {
+        command = "open";
+        args = [url];
+    }
+    else {
+        command = "xdg-open";
+        args = [url];
+    }
+
+    const child = spawn(command, args, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+}
+
+function protocolConfig(config, values) {
+    if (values.http && values.https)
+        throw new Error("--http and --https are mutually exclusive");
+
+    let https = config.dev.https;
+    if (values.http)
+        https = false;
+    if (values.https)
+        https = true;
+
+    return https;
+}
+
+function serverUrl(host, port, https) {
+    let displayHost = host;
+    if (host === "0.0.0.0")
+        displayHost = "127.0.0.1";
+    else if (host === "::")
+        displayHost = "[::1]";
+    else if (host.includes(":") && !host.startsWith("["))
+        displayHost = `[${host}]`;
+    return `${https ? "https" : "http"}://${displayHost}:${port}/`;
+}
+
+export async function dev(argv = [], root = process.cwd()) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            host: { type: "string" },
+            port: { type: "string" },
+            http: { type: "boolean", default: false },
+            https: { type: "boolean", default: false },
+            open: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+
+    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");
+
+    let context;
+    let packageWatcher;
+    let stopping = false;
+    let restartTimer;
+    let restartChain = Promise.resolve();
+    let browserOpened = false;
+
+    async function start(config) {
+        const host = values.host ?? config.dev.host;
+        const port = values.port === undefined ? config.dev.port : Number(values.port);
+        if (port < 0 || port > 65535)
+            throw new Error("--port must be between 0 and 65535");
+
+        const useHttps = protocolConfig(config, values);
+        const serveOptions = {
+            host,
+            port,
+            servedir: config.outdir,
+        };
+
+        if (useHttps)
+            Object.assign(serveOptions, resolveTls(config));
+
+        const next = await esbuild.context(createBuildOptions(config, "dev"));
+        try {
+            await next.watch();
+            const result = await next.serve(serveOptions);
+            context = next;
+
+            const actualHost = result.hosts.includes(host) ? host : (result.hosts[0] ?? host);
+            const url = serverUrl(actualHost, result.port, useHttps);
+            info("mode", "dev");
+            info("outdir", config.outdir);
+            success("listening", url);
+
+            if (values.open && !browserOpened) {
+                browserOpened = true;
+                openBrowser(url);
+            }
+        }
+        catch (error) {
+            await next.dispose();
+            throw error;
+        }
+    }
+
+    async function reload() {
+        let config;
+        try {
+            config = loadConfig(root);
+            protocolConfig(config, values);
+            if ((values.https || (!values.http && config.dev.https)))
+                resolveTls(config);
+        }
+        catch (error) {
+            failure(`config: ${error.message}`);
+            return;
+        }
+
+        const previous = context;
+        context = undefined;
+        if (previous)
+            await previous.dispose();
+
+        try {
+            await start(config);
+            success("config", "reloaded");
+        }
+        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.
+        }
+    }
+
+    function scheduleReload() {
+        clearTimeout(restartTimer);
+        restartTimer = setTimeout(() => {
+            restartChain = restartChain.then(reload, reload);
+        }, 150);
+    }
+
+    const initialConfig = loadConfig(root);
+    await start(initialConfig);
+
+    packageWatcher = fs.watch(path.resolve(root), { persistent: true }, (_event, filename) => {
+        if (filename === null || filename.toString() === "package.json")
+            scheduleReload();
+    });
+
+    async function stop() {
+        if (stopping)
+            return;
+        stopping = true;
+        clearTimeout(restartTimer);
+        packageWatcher?.close();
+        await restartChain.catch(() => {});
+        await context?.dispose();
+    }
+
+    process.once("SIGINT", async () => {
+        await stop();
+        process.exit(0);
+    });
+    process.once("SIGTERM", async () => {
+        await stop();
+        process.exit(0);
+    });
+
+    return { stop };
+}

package/cli/less-plugin.mjs

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+async function loadLess(projectRoot) {
+    const require = createRequire(path.join(projectRoot, "package.json"));
+    let resolved;
+    try {
+        resolved = require.resolve("less");
+    }
+    catch {
+        throw new Error(
+            'LESS support requires the "less" package.\n' +
+            'Install it with: npm install -D less',
+        );
+    }
+
+    const module = await import(pathToFileURL(resolved).href);
+    return module.default ?? module;
+}
+
+export function lessPlugin(projectRoot) {
+    let lessPromise;
+
+    return {
+        name: "x4-less",
+        setup(build) {
+            build.onLoad({ filter: /\.less$/ }, async (args) => {
+                const source = await fs.readFile(args.path, "utf8");
+                lessPromise ??= loadLess(projectRoot);
+                const less = await lessPromise;
+
+                const result = await less.render(source, {
+                    filename: args.path,
+                });
+
+                return {
+                    contents: result.css,
+                    loader: "css",
+                    resolveDir: path.dirname(args.path),
+                    watchFiles: [args.path, ...(result.imports ?? [])],
+                };
+            });
+        },
+    };
+}

package/cli/log.mjs

@@ -0,0 +1,41 @@
+import { styleText } from "node:util";
+
+function useColor(stream = process.stdout) {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined)
+        return process.env.FORCE_COLOR !== "0";
+    return !!stream.isTTY;
+}
+
+function paint(style, value, stream = process.stdout) {
+    const text = String(value);
+    return useColor(stream) ? styleText(style, text) : text;
+}
+
+export const color = {
+    cyan: (value) => paint("cyan", value),
+    green: (value) => paint("green", value),
+    yellow: (value) => paint("yellow", value),
+    red: (value) => paint("red", value, process.stderr),
+    gray: (value) => paint("gray", value),
+    white: (value) => paint("white", value),
+};
+
+export function info(label, value = "") {
+    const left = color.cyan(String(label).padEnd(11));
+    console.log(value === "" ? left.trimEnd() : `${left}${value}`);
+}
+
+export function success(label, value = "") {
+    const left = color.green(String(label).padEnd(11));
+    console.log(value === "" ? left.trimEnd() : `${left}${value}`);
+}
+
+export function warning(message) {
+    console.warn(color.yellow(message));
+}
+
+export function failure(message) {
+    console.error(color.red(message));
+}

package/cli/main.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { failure } from "./log.mjs";
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const packageFile = path.join(cliDir, "..", "package.json");
+
+function getVersion() {
+    try {
+        return JSON.parse(fs.readFileSync(packageFile, "utf8")).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+
+function printHelp(version) {
+    console.log(`x4js ${version}
+
+Usage:
+  x4js create <project> [--template <name>] [--no-install]
+  x4js templates
+  x4js dev [--host <host>] [--port <port>] [--http|--https] [--open]
+  x4js build [--debug]
+
+Options:
+  -h, --help       Show help
+  -v, --version    Show version`);
+}
+
+const version = getVersion();
+const [command, ...argv] = process.argv.slice(2);
+
+try {
+    switch (command) {
+        case "create": {
+            const { create } = await import("./create.mjs");
+            await create(argv, { version });
+            break;
+        }
+        case "templates": {
+            const { templates } = await import("./templates.mjs");
+            await templates(argv, { version });
+            break;
+        }
+        case "dev": {
+            const { dev } = await import("./dev.mjs");
+            await dev(argv);
+            break;
+        }
+        case "build": {
+            const { build } = await import("./build.mjs");
+            await build(argv);
+            break;
+        }
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp(version);
+            break;
+        case "--version":
+        case "-v":
+            console.log(version);
+            break;
+        default:
+            throw new Error(`Unknown command '${command}'. Run 'x4js --help'.`);
+    }
+}
+catch (error) {
+    failure(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/cli/templates-source.mjs

@@ -0,0 +1,61 @@
+const OWNER = "rlibre";
+const REPO = "x4-templates";
+const REF = "main";
+
+function headers(version = "unknown") {
+    return {
+        "Accept": "application/vnd.github+json",
+        "User-Agent": `x4js/${version}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+}
+
+async function checkedFetch(url, options) {
+    const response = await fetch(url, options);
+    if (!response.ok)
+        throw new Error(`Template repository request failed (${response.status} ${response.statusText})`);
+    return response;
+}
+
+export async function fetchTemplates(version = "unknown") {
+    const url = `https://raw.githubusercontent.com/${OWNER}/${REPO}/${REF}/templates.json`;
+    const response = await checkedFetch(url, { headers: headers(version) });
+    const manifest = await response.json();
+
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("Invalid templates.json");
+
+    for (const [name, description] of Object.entries(manifest)) {
+        if (!name || typeof description !== "string")
+            throw new Error("Invalid templates.json entry");
+    }
+
+    return manifest;
+}
+
+export async function fetchTemplateFiles(name, version = "unknown") {
+    const treeUrl = `https://api.github.com/repos/${OWNER}/${REPO}/git/trees/${REF}?recursive=1`;
+    const response = await checkedFetch(treeUrl, { headers: headers(version) });
+    const tree = await response.json();
+
+    if (!Array.isArray(tree.tree))
+        throw new Error("Invalid template repository tree");
+
+    const prefix = `${name}/`;
+    const files = tree.tree
+        .filter((item) => item.type === "blob" && item.path.startsWith(prefix))
+        .map((item) => ({
+            path: item.path.slice(prefix.length),
+            url: `https://raw.githubusercontent.com/${OWNER}/${REPO}/${REF}/${item.path.split("/").map(encodeURIComponent).join("/")}`,
+        }));
+
+    if (!files.length)
+        throw new Error(`Template '${name}' contains no files`);
+
+    return files;
+}
+
+export async function downloadTemplateFile(url, version = "unknown") {
+    const response = await checkedFetch(url, { headers: headers(version) });
+    return Buffer.from(await response.arrayBuffer());
+}

package/cli/templates.mjs

@@ -0,0 +1,13 @@
+import { fetchTemplates } from "./templates-source.mjs";
+import { color } from "./log.mjs";
+
+export async function templates(_argv = [], { version = "unknown" } = {}) {
+    const manifest = await fetchTemplates(version);
+    const names = Object.keys(manifest).sort();
+    const width = names.reduce((max, name) => Math.max(max, name.length), 0) + 3;
+
+    console.log(color.cyan("Available templates"));
+    console.log();
+    for (const name of names)
+        console.log(`  ${color.green(name.padEnd(width))}${manifest[name]}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.2.73",
+  "version": "2.3.1",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",
@@ -9,6 +9,9 @@
     ".": "./src/x4.ts",
     "./monaco": "./src/components/monaco/monaco.ts"
   },
+  "bin": {
+    "x4js": "./bin/x4js.mjs"
+  },
   "scripts": {
     "build-publish": "deno run --allow-all ./publish.ts",
     "build-doc": "typedoc",
@@ -16,6 +19,8 @@
   },
   "files": [
     "src",
+    "bin",
+    "cli",
     "README.md",
     "LICENSE"
   ],
@@ -32,6 +37,10 @@
     "desktop",
     "application"
   ],
+  "dependencies": {
+    "esbuild": "0.28",
+    "esbuild-sass-plugin": "^3.7"
+  },
   "devDependencies": {
     "typescript": "^5.8.3",
     "typedoc": "^0.28.19",

package/readme.npm.md

@@ -0,0 +1,248 @@
+# x4js
+
+**A TypeScript framework for building applications, not markup.**
+
+x4js is designed for rich web and desktop applications: business software, industrial interfaces, dashboards, data-heavy tools and desktop-like applications.
+
+It uses persistent TypeScript objects associated with the real DOM. No virtual DOM, no reconciliation layer, and no application architecture imposed by JSX.
+
+**TypeScript objects. JSX when it helps. Real DOM.**
+
+## Install
+
+```bash
+npm install x4js
+```
+
+## Quick start
+
+Create a project:
+
+```bash
+npx x4build create demo --type=html
+cd demo
+npm install
+```
+
+Run it in development mode with HMR:
+
+```bash
+npx x4build --watch --hmr --serve
+```
+
+## More than 50 UI components
+
+x4 includes a complete UI toolkit for building real applications.
+
+Among the available components:
+
+`Button`, `Input`, `TextEdit`, `TextArea`, `Checkbox`, `Radio`, `Switch`, `Select`, `Combobox`, `Slider`, `ColorPicker`, `Form`, `Dialog`, `Popup`, `Menu`, `Tabs`, `Gridview`, `Treeview`, `PropertyGrid`, `Spreadsheet`, `Calendar`, `Gauge`, `Progress`, `FileDrop`, `MonacoEditor`, layouts and more.
+
+The framework also provides:
+
+* drag & drop
+* SVG primitives and builder
+* routing
+* PDF generation
+* internationalization
+* data stores and views
+* application-wide events
+* persistence helpers
+* CSS infrastructure and theming
+
+## Easy to extend
+
+x4 components are ordinary TypeScript classes.
+
+```ts
+import { Component, ComponentProps } from 'x4js'
+
+interface StatusBadgeProps extends ComponentProps {
+    text: string
+}
+
+class StatusBadge extends Component<StatusBadgeProps> {
+    constructor(props: StatusBadgeProps) {
+        super(props)
+
+        this.setContent(props.text)
+    }
+}
+```
+
+Your own components use the same DOM, lifecycle and event model as the components provided by x4.
+
+Because x4 works with the real browser DOM, third-party UI libraries can also be integrated where they make sense. There is no separate plugin architecture to satisfy.
+
+## Real DOM
+
+A `Component` is a persistent TypeScript object associated with an actual DOM element.
+
+```ts
+const button = new Button({
+    label: 'Restart'
+})
+
+button.on('click', () => restartMachine())
+```
+
+The object remains alive for the lifetime of the component. You can keep references, call methods and listen to events directly.
+
+There is no virtual tree to rebuild or reconcile.
+
+## JSX is optional
+
+x4 supports JSX, but JSX is syntax — not the application architecture.
+
+Object API:
+
+```ts
+this.setContent([
+    new Label({
+        text: 'Temperature'
+    }),
+
+    new Gauge({
+        min: 0,
+        max: 100
+    })
+])
+```
+
+JSX:
+
+```tsx
+this.setContent(
+    <VBox>
+        <Label text="Temperature" />
+        <Gauge min={0} max={100} />
+    </VBox>
+)
+```
+
+Both create the same x4 Components and the same real DOM.
+
+Use whichever makes the code clearer.
+
+## Data-heavy applications
+
+x4 treats grids, trees, forms and structured data as first-class application concerns.
+
+`DataStore`, `DataView` and `Gridview` are designed to work together for tabular data:
+
+```ts
+const store = new DataStore({
+    model,
+    data
+})
+
+const grid = new Gridview({
+    store,
+    columns: [
+        { id: 'name', title: 'Name', width: 200 },
+        { id: 'age', title: 'Age', width: 80 }
+    ]
+})
+```
+
+Changes to the data are reflected by the components using it.
+
+## Routing
+
+```ts
+const router = new Router(true)
+
+router.get('/home', () => showHome())
+router.get('/device/:id', p => showDevice(p.id))
+
+router.init()
+```
+
+## Internationalization
+
+Internationalization support is built in.
+
+```ts
+createLanguage('de', 'en')
+addTranslation('de', translations)
+
+selectLanguage('de')
+```
+
+x4 includes French and English translations by default and allows applications to add their own languages.
+
+## SVG and PDF
+
+SVG is part of the framework surface through `SvgComponent` and `SvgBuilder`.
+
+PDF documents can be generated programmatically with `X4PDFBuilder`:
+
+```ts
+const pdf = new X4PDFBuilder()
+
+pdf.page(595, 842, page => {
+    // draw page
+})
+
+const data = pdf.build()
+```
+
+## CSS and themes
+
+x4 includes the CSS foundation used by its components.
+
+Applications can use the default styling, adapt it to their product, or provide their own CSS. Components expose their real DOM and CSS classes, so standard browser styling techniques remain available.
+
+No CSS-in-JS runtime is required.
+
+## HMR and development workflow
+
+The standard x4 build workflow supports watch mode, development serving and HMR:
+
+```bash
+x4build --watch --hmr --serve
+```
+
+Edit the application, save, see the result.
+
+## Ship only what you use
+
+The `x4js` npm package ships its TypeScript sources directly.
+
+Your application and x4 therefore participate in the same module graph, allowing the bundler to tree-shake unused code.
+
+Import a small part of x4 and the rest of the component library does not need to become part of your application bundle.
+
+## Web and desktop
+
+x4 targets both browser and desktop applications.
+
+The same component model can be used in the browser or inside a desktop wrapper such as Electron, Tauri or NW.js.
+
+## AI-friendly documentation
+
+x4 provides a generated `aicontext.md` containing the actual TypeScript API signatures.
+
+AI coding agents can also inspect the framework sources directly because they are distributed with the npm package:
+
+```text
+node_modules/x4js/src/
+```
+
+The goal is not to make x4 an “AI framework”.
+
+The goal is simpler: an explicit architecture and an API that are readable by humans and predictable for machines.
+
+## Philosophy
+
+x4 deliberately keeps its conceptual model small.
+
+Use TypeScript when TypeScript is enough.
+Use the browser when the browser is enough.
+Add an abstraction only when it solves a real problem.
+
+**Use the simplest tool that fits.**
+
+---
+
+MIT License