lumix-js 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+The `lumix-js` package provides a modular, fine-grained reactive runtime. It is the core engine that powers state management and DOM updates, and it also contains the primary LumixJS CLI.
+
+## CLI Core Commands
+
+The `lumix` binary is the entry point for managing LumixJS projects.
+
+### `lumix init`
+
+Creates a new project from a template.
+
+```bash
+lumix init <project-name>
+```
+
+### `lumix dev`
+
+Starts the development server.
+
+```bash
+lumix dev
+```
+
+### `lumix build`
+
+Builds the project for production, generating compiled assets.
+
+```bash
+lumix build
+```
+
+## Core Concepts
+
+The runtime is built on the principle of fine-grained reactivity, using Signals and Effects to ensure that only the parts of the DOM that actually change are updated.
+
+### Signals
+
+Signals are the primary primitive for reactive state. A signal holds a value and notifies its subscribers when that value changes.
+
+```typescript
+import { signal } from "lumix-js";
+
+const count = signal(0);
+
+// Read value
+console.log(count());
+
+// Update value
+count(count() + 1);
+
+// Bulk update with .value
+count.value = 10;
+```
+
+### Effects
+
+Effects are functions that automatically re-run whenever the signals they depend on change.
+
+```typescript
+import { signal, effect } from "lumix-js";
+
+const name = signal("Lumin");
+
+effect(() => {
+  console.log(`Hello, ${name()}!`);
+});
+
+name("World"); // Logs: "Hello, World!"
+```
+
+### Computed Signals
+
+Computed signals derive their value from other signals. They are automatically updated whenever their dependencies change.
+
+```typescript
+import { signal, computed } from "lumix-js";
+
+const first = signal("John");
+const last = signal("Doe");
+
+const full = computed(() => `${first()} ${last()}`);
+
+console.log(full()); // "John Doe"
+```
+
+## Lifecycle Hooks
+
+LumixJS provides hooks for managing component lifecycles.
+
+- `onMount(fn)`: Executes when the component is mounted to the DOM.
+- `onDestroy(fn)`: Executes when the component is unmounted.
+
+## Global State Management (Store)
+
+For complex state that needs to be shared across components or persisted, LumixJS provides a robust Store system.
+
+```typescript
+import { store, persist } from "lumix-js";
+
+// Create a reactive store
+const auth = store({
+  user: null,
+  isLoggedIn: false,
+});
+
+// Update multiple values in a batch
+auth.update({ user: "LuminUser", isLoggedIn: true });
+
+// Reactively listen to all changes
+auth.subscribe((state) => {
+  console.log("Auth changed:", state);
+});
+
+// Persist automatically to localStorage
+persist(auth, { key: "lumin_auth" });
+```
+
+## Two-Way Binding
+
+The `bind` helper simplifies the synchronization between UI elements and signals.
+
+```svelte
+<script>
+  import { signal, bind } from "lumix-js";
+
+  const email = signal("");
+</script>
+
+<div class="field">
+    <label>Email</label>
+    <input type="email" bind:value={email} />
+</div>
+```
+
+The runtime includes specific helpers for different input types:
+
+- `bindValue`: For text inputs, textareas, and selects.
+- `bindChecked`: For checkboxes.
+- `bindNumeric`: For number and range inputs.
+- `bindGroup`: For radio button groups.
+- `bindSelected`: For multiple selects.
+
+## Universal Rendering
+
+The runtime includes primitives for both Server-Side Rendering (SSR) and Client-Side Hydration.
+
+- `renderToString(component)`: Produces a static HTML string.
+- `hydrate(root, component)`: Attaches event listeners and reactivity to existing HTML.
+
+## Advanced Control
+
+- `batch(fn)`: Batches multiple signal updates to trigger effects only once.
+- `untrack(fn)`: Executes a function without tracking dependencies.
+
+## License
+
+MIT

package/bin/lumix.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { dev } from "../dist/cli/dev.js";
+import { build } from "../dist/cli/build.js";
+import { preview } from "../dist/cli/preview.js";
+import { init } from "../dist/cli/init.js";
+
+const VERSION = "0.1.0";
+
+const program = new Command();
+
+program
+  .name("lumix")
+  .description("CLI for the LumixJS framework")
+  .version(VERSION);
+
+program.command("dev").description("Start the development server").action(dev);
+
+program
+  .command("build")
+  .description("Build the project for production")
+  .action(build);
+
+program
+  .command("preview")
+  .description("Preview the production build locally")
+  .action(preview);
+
+program
+  .command("init")
+  .description("Scaffold a new LuminJS project")
+  .argument("[name]", "Project name")
+  .option("-t, --template <template>", "Project template (blank, blank-ts)")
+  .action((name, options) => init(name, options));
+
+// Custom help output
+program.configureHelp({
+  formatHelp(cmd, helper) {
+    const title = `\n  ${pc.bold(pc.cyan("⚡ LumixJS"))} ${pc.dim(`v${VERSION}`)}\n`;
+    const desc = `  ${pc.dim(cmd.description())}\n`;
+
+    const cmds = cmd.commands.map((c) => {
+      const name = c.name().padEnd(12);
+      return `    ${pc.green(name)} ${pc.dim(c.description())}`;
+    });
+
+    const cmdSection = `\n  ${pc.bold("Commands:")}\n${cmds.join("\n")}\n`;
+
+    const opts = cmd.options.map((o) => {
+      const flags = o.flags.padEnd(18);
+      return `    ${pc.yellow(flags)} ${pc.dim(o.description)}`;
+    });
+
+    const optSection = `\n  ${pc.bold("Options:")}\n${opts.join("\n")}\n`;
+
+    const usage = `\n  ${pc.bold("Usage:")}  ${pc.dim("lumix")} ${pc.white("<command>")} ${pc.dim("[options]")}\n`;
+
+    return title + desc + usage + cmdSection + optSection + "\n";
+  },
+});
+
+program.parse();

package/dist/bind.d.ts

@@ -0,0 +1,13 @@
+import { Signal } from "./signals.js";
+/** Two-way binding for text inputs, textareas, and selects */
+export declare function bindValue(el: HTMLElement, sig: Signal<string>): void;
+/** Two-way binding for checkboxes */
+export declare function bindChecked(el: HTMLElement, sig: Signal<boolean>): void;
+/** Two-way binding for number/range inputs */
+export declare function bindNumeric(el: HTMLElement, sig: Signal<number>): void;
+/** Two-way binding for radio button groups */
+export declare function bindGroup(el: HTMLElement, sig: Signal<string>): void;
+/** Two-way binding for `<select multiple>` */
+export declare function bindSelected(el: HTMLElement, sig: Signal<string[]>): void;
+/** Automatically detect input type and apply the right bind */
+export declare function bind(el: HTMLElement, property: string, sig: Signal<any>): void;

package/dist/bind.js

@@ -0,0 +1,103 @@
+import { effect } from "./signals.js";
+// ─── Core bind helper ──────────────────────────────────────
+function setupBind(el, sig, domProp, event, transform) {
+    // Signal → DOM
+    effect(() => {
+        const v = sig();
+        el[domProp] = v;
+    });
+    // DOM → Signal
+    el.addEventListener(event, () => {
+        const raw = el[domProp];
+        sig(transform ? transform(raw) : raw);
+    });
+}
+// ─── bindValue ─────────────────────────────────────────────
+/** Two-way binding for text inputs, textareas, and selects */
+export function bindValue(el, sig) {
+    const tag = el.tagName.toLowerCase();
+    const event = tag === "select" ? "change" : "input";
+    setupBind(el, sig, "value", event);
+}
+// ─── bindChecked ───────────────────────────────────────────
+/** Two-way binding for checkboxes */
+export function bindChecked(el, sig) {
+    setupBind(el, sig, "checked", "change");
+}
+// ─── bindNumeric ───────────────────────────────────────────
+/** Two-way binding for number/range inputs */
+export function bindNumeric(el, sig) {
+    // Signal → DOM
+    effect(() => {
+        el.value = String(sig());
+    });
+    // DOM → Signal (using valueAsNumber)
+    el.addEventListener("input", () => {
+        const n = el.valueAsNumber;
+        if (!Number.isNaN(n))
+            sig(n);
+    });
+}
+// ─── bindGroup ─────────────────────────────────────────────
+/** Two-way binding for radio button groups */
+export function bindGroup(el, sig) {
+    // Signal → DOM
+    effect(() => {
+        el.checked = el.value === sig();
+    });
+    // DOM → Signal
+    el.addEventListener("change", () => {
+        if (el.checked) {
+            sig(el.value);
+        }
+    });
+}
+// ─── bindSelected ──────────────────────────────────────────
+/** Two-way binding for `<select multiple>` */
+export function bindSelected(el, sig) {
+    const select = el;
+    // Signal → DOM
+    effect(() => {
+        const selected = sig();
+        for (const opt of Array.from(select.options)) {
+            opt.selected = selected.includes(opt.value);
+        }
+    });
+    // DOM → Signal
+    select.addEventListener("change", () => {
+        const values = [];
+        for (const opt of Array.from(select.selectedOptions)) {
+            values.push(opt.value);
+        }
+        sig(values);
+    });
+}
+// ─── Auto-detect bind ──────────────────────────────────────
+/** Automatically detect input type and apply the right bind */
+export function bind(el, property, sig) {
+    const tag = el.tagName.toLowerCase();
+    const type = el.type?.toLowerCase() || "";
+    switch (property) {
+        case "value":
+            if (tag === "input" && (type === "number" || type === "range")) {
+                bindNumeric(el, sig);
+            }
+            else {
+                bindValue(el, sig);
+            }
+            break;
+        case "checked":
+            bindChecked(el, sig);
+            break;
+        case "group":
+            bindGroup(el, sig);
+            break;
+        case "selected":
+            bindSelected(el, sig);
+            break;
+        default:
+            // Generic: treat as a property bind
+            setupBind(el, sig, property, "input");
+            break;
+    }
+}

package/dist/cli/build.d.ts

@@ -0,0 +1 @@
+export declare function build(): Promise<void>;

package/dist/cli/build.js

@@ -0,0 +1,69 @@
+import { build as viteBuild } from "vite";
+import lumix from "../../../vite-plugin-lumix/dist/index.js";
+import pc from "picocolors";
+import { loadConfig } from "./loader.js";
+import path from "path";
+import fs from "fs-extra";
+import { __dirname } from "./utils.js";
+export async function build() {
+    const cwd = process.cwd();
+    const config = await loadConfig(cwd);
+    console.log("");
+    console.log(`  ${pc.bold(pc.cyan("⚡ LumixJS"))} ${pc.dim("v0.1.0")}`);
+    console.log(pc.dim("  Building for production...\n"));
+    const indexPath = path.join(cwd, "index.html");
+    const hasIndex = fs.existsSync(indexPath);
+    let tempIndex = false;
+    try {
+        if (!hasIndex) {
+            tempIndex = true;
+            // Auto-detect entry: main.ts > main.js
+            const entry = fs.existsSync(path.join(cwd, "main.ts"))
+                ? "/main.ts"
+                : "/main.js";
+            const defaultHtml = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+  <div id="${config?.rootId || "app"}"></div>
+  <script type="module" src="${entry}"></script>
+</body>
+</html>
+      `.trim();
+            fs.writeFileSync(indexPath, defaultHtml);
+        }
+        await viteBuild({
+            root: cwd,
+            base: "/",
+            plugins: [lumix(config), ...(config.vite?.plugins || [])],
+            build: {
+                outDir: "dist",
+                emptyOutDir: true,
+                ...config.vite?.build,
+            },
+            resolve: {
+                alias: {
+                    "lumix-js": path.resolve(__dirname, "../index.js"),
+                    ...config.vite?.resolve?.alias,
+                },
+            },
+            ...config.vite,
+        });
+        console.log(pc.green(pc.bold("\n  Build completed successfully!")));
+        console.log(pc.dim(`  Output directory: ${pc.white("./dist")}\n`));
+    }
+    catch (e) {
+        console.error(pc.red(pc.bold("\n  Build failed!")));
+        console.error(pc.red(`  ${e.message}\n`));
+        process.exit(1);
+    }
+    finally {
+        if (tempIndex && fs.existsSync(indexPath)) {
+            fs.removeSync(indexPath);
+        }
+    }
+}

package/dist/cli/dev.d.ts

@@ -0,0 +1 @@
+export declare function dev(): Promise<void>;

package/dist/cli/dev.js

@@ -0,0 +1,69 @@
+import { createServer } from "vite";
+import lumix from "../../../vite-plugin-lumix/dist/index.js";
+import pc from "picocolors";
+import { loadConfig, findConfigPath } from "./loader.js";
+import path from "path";
+import fs from "fs";
+import { __dirname } from "./utils.js";
+async function startServer(cwd) {
+    const config = await loadConfig(cwd);
+    const server = await createServer({
+        root: cwd,
+        base: "/",
+        mode: "development",
+        plugins: [lumix(config), ...(config.vite?.plugins || [])],
+        server: {
+            port: 3000,
+            ...config.vite?.server,
+        },
+        resolve: {
+            alias: {
+                "lumix-js": path.resolve(__dirname, "../index.js"),
+                ...config.vite?.resolve?.alias,
+            },
+        },
+        ...config.vite,
+    });
+    await server.listen();
+    return server;
+}
+export async function dev() {
+    const cwd = process.cwd();
+    console.log("");
+    console.log(`  ${pc.bold(pc.cyan("⚡ LumixJS"))} ${pc.dim("v0.1.0")}`);
+    console.log(pc.dim("  Starting development server...\n"));
+    try {
+        let server = await startServer(cwd);
+        const port = server.config.server.port;
+        console.log(`  ${pc.green("➜")}  ${pc.bold("Local:")}   ${pc.cyan(`http://localhost:${port}/`)}`);
+        console.log(`  ${pc.green("➜")}  ${pc.dim("Ready in")} ${pc.white(Math.round(performance.now()))}ms\n`);
+        // Watch config file for changes
+        const configPath = findConfigPath(cwd);
+        if (configPath) {
+            let debounce = null;
+            fs.watch(configPath, () => {
+                if (debounce)
+                    return;
+                debounce = setTimeout(async () => {
+                    debounce = null;
+                    console.log(`\n  ${pc.yellow("↻")}  ${pc.dim("Config changed, restarting...")}`);
+                    try {
+                        await server.close();
+                        server = await startServer(cwd);
+                        const newPort = server.config.server.port;
+                        console.log(`  ${pc.green("➜")}  ${pc.bold("Local:")}   ${pc.cyan(`http://localhost:${newPort}/`)}`);
+                        console.log(`  ${pc.green("➜")}  ${pc.dim("Restarted successfully")}\n`);
+                    }
+                    catch (e) {
+                        console.error(pc.red(`  ✗  Restart failed: ${e.message}\n`));
+                    }
+                }, 300);
+            });
+        }
+    }
+    catch (e) {
+        console.error(pc.red(pc.bold("\n  Failed to start server:")));
+        console.error(pc.red(`  ${e.message}\n`));
+        process.exit(1);
+    }
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,5 @@
+type InitOptions = {
+    template?: string;
+};
+export declare function init(name?: string, options?: InitOptions): Promise<void>;
+export {};

package/dist/cli/init.js

@@ -0,0 +1,199 @@
+import prompts from "prompts";
+import pc from "picocolors";
+import fs from "fs-extra";
+import path from "path";
+import { __dirname } from "./utils.js";
+import { spawnSync } from "child_process";
+function hasCommand(cmd) {
+    const which = process.platform === "win32" ? "where" : "which";
+    const res = spawnSync(which, [cmd], { stdio: "ignore" });
+    return res.status === 0;
+}
+function detectPackageManager() {
+    if (hasCommand("bun"))
+        return "bun";
+    if (hasCommand("pnpm"))
+        return "pnpm";
+    return "npm";
+}
+function getInstalledPackageManagers() {
+    const out = [];
+    if (hasCommand("bun"))
+        out.push("bun");
+    if (hasCommand("pnpm"))
+        out.push("pnpm");
+    out.push("npm");
+    return Array.from(new Set(out));
+}
+function runDevCommand(pm) {
+    if (pm === "npm")
+        return "npm run dev";
+    return `${pm} run dev`;
+}
+function installCommand(pm) {
+    if (pm === "npm")
+        return "npm install";
+    return `${pm} install`;
+}
+function runInstall(pm, cwd) {
+    const cmd = pm;
+    const args = ["install"];
+    const res = spawnSync(cmd, args, { cwd, stdio: "inherit" });
+    if (res.error)
+        throw res.error;
+    if (res.signal === "SIGINT") {
+        const err = new Error("install interrupted");
+        err.code = "SIGINT";
+        throw err;
+    }
+    if (typeof res.status === "number" && res.status !== 0) {
+        throw new Error(`${cmd} install failed with exit code ${res.status}`);
+    }
+}
+function isEnoentSpawnError(e) {
+    return Boolean(e && typeof e === "object" && "code" in e && e.code === "ENOENT");
+}
+function isSigintError(e) {
+    return Boolean(e && typeof e === "object" && "code" in e && e.code === "SIGINT");
+}
+export async function init(name, options) {
+    console.log("");
+    console.log(`  ${pc.bold(pc.cyan("⚡ LumixJS"))} ${pc.dim("v0.1.0")}`);
+    console.log(pc.dim("  Scaffolding a new project...\n"));
+    const templates = [
+        { title: "Blank", value: "blank" },
+        { title: "Blank (TypeScript)", value: "blank-ts" },
+        { title: "Sitemap (Coming soon...)", value: "sitemap", disabled: true },
+    ];
+    const allowedTemplates = new Set(templates
+        .filter((t) => !t.disabled)
+        .map((t) => t.value));
+    let template = options?.template;
+    if (template && !allowedTemplates.has(template)) {
+        console.log(pc.red(`\n  Error: Unknown template "${template}". Valid templates are: ${[...allowedTemplates].join(", ")}.\n`));
+        process.exit(1);
+    }
+    const questions = [];
+    if (!name) {
+        questions.push({
+            type: "text",
+            name: "projectName",
+            message: "Project name:",
+            initial: "my-lumin-app",
+        });
+    }
+    if (!template) {
+        questions.push({
+            type: "select",
+            name: "template",
+            message: "Pick a template:",
+            choices: templates,
+        });
+    }
+    const detectedPm = detectPackageManager();
+    const installedPms = getInstalledPackageManagers();
+    questions.push({
+        type: "toggle",
+        name: "install",
+        message: "Install dependencies?",
+        initial: true,
+        active: "yes",
+        inactive: "no",
+    });
+    questions.push({
+        type: (prev) => (prev ? "select" : null),
+        name: "packageManager",
+        message: "Package manager:",
+        initial: Math.max(0, installedPms.indexOf(detectedPm)),
+        choices: installedPms.map((pm) => ({ title: pm, value: pm })),
+    });
+    const response = questions.length > 0
+        ? await prompts(questions, {
+            onCancel() {
+                console.log(pc.red("\n  Aborted.\n"));
+                process.exit(0);
+            },
+        })
+        : {};
+    const projectName = name || response.projectName;
+    template = template || response.template;
+    const shouldInstall = response.install !== false;
+    const selected = (response.packageManager || detectedPm);
+    let packageManager = selected;
+    if (!projectName || !template) {
+        console.log(pc.red("\n  Aborted.\n"));
+        process.exit(0);
+    }
+    const targetDir = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(targetDir)) {
+        console.log(pc.red(`\n  Error: Directory "${projectName}" already exists.\n`));
+        process.exit(1);
+    }
+    const templateDir = path.resolve(__dirname, "../../templates", template);
+    console.log(pc.dim("\n  Scaffolding project..."));
+    try {
+        await fs.ensureDir(targetDir);
+        await fs.copy(templateDir, targetDir);
+        // Update package.json name
+        const pkgPath = path.join(targetDir, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = await fs.readJson(pkgPath);
+            pkg.name = projectName;
+            await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+        }
+        console.log(pc.green(pc.bold("\n  Success! Project created.")));
+        if (shouldInstall) {
+            console.log(pc.dim(`\n  Installing dependencies (${packageManager})...`));
+            try {
+                runInstall(packageManager, targetDir);
+                console.log(pc.green(pc.bold("\n  Dependencies installed.")));
+            }
+            catch (e) {
+                if (isSigintError(e)) {
+                    console.log(pc.red("\n  Aborted.\n"));
+                    process.exit(0);
+                }
+                if (isEnoentSpawnError(e)) {
+                    const fallback = detectedPm;
+                    if (fallback !== packageManager && hasCommand(fallback)) {
+                        console.log(pc.yellow(`\n  ${packageManager} not found. Retrying with ${fallback}...`));
+                        try {
+                            packageManager = fallback;
+                            runInstall(packageManager, targetDir);
+                            console.log(pc.green(pc.bold("\n  Dependencies installed.")));
+                        }
+                        catch (e2) {
+                            if (isSigintError(e2)) {
+                                console.log(pc.red("\n  Aborted.\n"));
+                                process.exit(0);
+                            }
+                            console.log(pc.red(`\n  Failed to install dependencies: ${e2?.message || e2}`));
+                            console.log(pc.dim("  Project created at:"));
+                            console.log(`    ${targetDir}\n`);
+                        }
+                    }
+                    else {
+                        console.log(pc.red(`\n  Failed to install dependencies: ${e?.message || e}`));
+                        console.log(pc.dim("  Project created at:"));
+                        console.log(`    ${targetDir}\n`);
+                    }
+                }
+                else {
+                    console.log(pc.red(`\n  Failed to install dependencies: ${e?.message || e}`));
+                    console.log(pc.dim("  Project created at:"));
+                    console.log(`    ${targetDir}\n`);
+                }
+            }
+        }
+        console.log(pc.dim("\n  Next steps:"));
+        console.log(`    cd ${projectName}`);
+        if (!shouldInstall) {
+            console.log(`    ${installCommand(packageManager)}`);
+        }
+        console.log(`    ${runDevCommand(packageManager)}\n`);
+    }
+    catch (e) {
+        console.error(pc.red(`\n  Failed to initialize project: ${e.message}\n`));
+        process.exit(1);
+    }
+}