flet-box 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maenys Javier Quesada Reyes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="src/assets/logo.png" alt="FletBox" width="110" />
+
+<h1>FletBox</h1>
+
+<b>Ship web, PWA, Android &amp; iOS from one codebase — with zero runtime dependencies.</b><br>
+A declarative, Flutter/Flet-like UI framework in plain vanilla JavaScript.<br>
+Real DOM · No Virtual DOM · No build config to learn.
+
+<br>
+
+<a href="https://github.com/sponsors/kuko53348"><img src="https://img.shields.io/badge/%E2%9D%A4%20Sponsor-FletBox-ff69b4?style=for-the-badge&logo=githubsponsors" alt="Sponsor FletBox"></a>
+<a href="https://www.youtube.com/@flet-box"><img src="https://img.shields.io/badge/YouTube-@flet--box-red?style=for-the-badge&logo=youtube" alt="YouTube @flet-box"></a>
+
+<br><br>
+
+<a href="https://github.com/kuko53348/flet-box/blob/HEAD/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>
+<img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="Zero dependencies">
+<img src="https://img.shields.io/badge/platforms-web%20%7C%20PWA%20%7C%20android%20%7C%20ios-007acc?style=flat-square" alt="Platforms">
+<a href="https://github.com/kuko53348/flet-box"><img src="https://img.shields.io/github/stars/kuko53348/flet-box?style=social" alt="GitHub stars"></a>
+
+<br><br>
+
+<a href="https://kuko53348.github.io/flet-box-docs/">📖 Docs</a> •
+<a href="#quick-start">Quick start</a> •
+<a href="https://www.youtube.com/@flet-box">▶ YouTube</a> •
+<a href="#support--sponsorship">❤️ Sponsor</a>
+
+</div>
+
+---
+
+**Stop paying the framework tax.** FletBox has no runtime dependencies, no Virtual DOM, and nothing to install beyond Node. Write widgets in the syntax you already know — plain JavaScript — and deploy to browser, PWA, Android, and iOS from the same source.
+
+> ▶ **Learn it on YouTube:** [@flet-box](https://www.youtube.com/@flet-box) — tutorials, walkthroughs, and new widgets.
+
+## Installation
+
+FletBox isn't on the npm registry, so clone it and link the CLI locally:
+
+```bash
+brew install node                 # macOS/Linux: ensure Node >= 18
+
+git clone https://github.com/kuko53348/flet-box.git
+cd flet-box
+npm link                          # link the flet-box CLI globally
+
+flet-box create appName           # scaffold your first app
+cd appName
+npm link flet-box                 # link FletBox into the new project
+flet-box run-spa                  # run as SPA with hot reload
+```
+
+## Quick start
+
+```javascript
+import { runApp, Container, Text, Button, useState } from "flet-box";
+
+const App = () => {
+  const [count, setCount] = useState("count", 0);
+
+  return Container({
+    width: "100%",
+    minHeight: "100vh",
+    display: "flex",
+    justifyContent: "center",
+    alignItems: "center",
+    child: [
+      Text({ text: `Counter: ${count}`, fontSize: 24, fontWeight: 700 }),
+      Button({ text: "Increment", onClick: () => setCount((v) => v + 1) }),
+    ],
+  });
+};
+
+runApp(App);
+```
+
+## Features
+
+- Declarative, widget-based UI · reactive state with `useState` · router for SPAs
+- Zero runtime dependencies; ESM only, Node >= 18 · real DOM, no Virtual DOM
+- Local storage, HTTP services, theme, PWA, and production builds
+- Android & iOS from the CLI (APK, simulator `.app`, `.xcarchive`)
+- Utility API for layout, text, color, animation, and more
+
+## Commands
+
+```bash
+npm run dev        # dev server on port 8000
+npm run build      # production bundle with esbuild
+
+# inside a generated project
+flet-box createBundle www      # bundle the app into www/
+flet-box build android         # Android debug APK
+flet-box build ios             # iOS Simulator app (macOS + Xcode)
+flet-box build ios --archive   # unsigned iOS archive, sign in Xcode
+```
+
+## Android and iOS
+
+`flet-box create` ships the Capacitor config, so the same SPA builds for both platforms. FletBox isn't on the npm registry — link it before installing:
+
+```bash
+flet-box create my-app && cd my-app
+npm link flet-box              # or: npm install ../path/to/flet-box
+npm install                    # Capacitor CLI, sharp, platform package
+```
+
+- **Android** — Node >= 20.9, a JDK, and the Android SDK. `flet-box build android` → debug APK; `flet-box build android --release [--aab]` → unsigned release artifact to sign yourself (`apksigner` / Play App Signing).
+- **iOS** — macOS, the **full** Xcode app (not Command Line Tools), a simulator runtime, and CocoaPods. `flet-box build ios` → simulator; `flet-box build ios --archive` → sign in Xcode.
+- Drop a 1024×1024 icon at `assets/logo.png` and rebuild — launcher icons, launch images, and the launch screen regenerate automatically.
+- Capacitor serves from `https://localhost`, so a remote API must allow that origin in CORS.
+
+Full guide, including manual `npx cap` workflows: [Mobile and platforms](docs/guides/mobile-and-platforms.md).
+
+## Documentation
+
+Read the docs online: **[The FletBox Book — kuko53348.github.io/flet-box-docs](https://kuko53348.github.io/flet-box-docs/)**.
+
+They are **one continuous book** — the cover maps every page: [The FletBox Book source](docs/README.md).
+
+- [Your first app](docs/guides/first-app.md) — build a working todo app in 20 minutes
+- [The widget book](docs/widget/README.md) — every widget with property tables and examples
+- [State, Router & Services](docs/guides/state.md) — shared state, routing, storage, and HTTP
+- [Tools & Utilities](docs/tools/README.md) — every helper function with signatures
+- [The CLI](docs/cli/README.md) — create, run, and build projects
+- [FletBox Server](docs/server/README.md) — backend toolkit: API, auth, security, data services
+- [SQLite and the API server](docs/server/data-services.md) — where your data lives + a full SQLite API example
+- [Mobile and platforms](docs/guides/mobile-and-platforms.md) — Android, iOS, PWA, and desktop
+- [Architecture](docs/arquitectura.md) — the widget contract and the single rendering engine
+- [Contributing](docs/CONTRIBUTING.md) — how to add code and docs
+
+## Support & sponsorship
+
+<div align="center">
+
+<a href="https://github.com/sponsors/kuko53348">
+  <img src="https://img.shields.io/badge/%E2%9D%A4%20Become_a_Sponsor-Support_FletBox-ff69b4?style=for-the-badge&logo=githubsponsors" alt="Become a Sponsor">
+</a>
+
+<br><br>
+
+**FletBox is MIT-licensed and free forever — for individuals and companies alike.**
+
+Zero dependencies. One developer. No corporate budget. Sponsoring is what keeps
+it independent — and what turns "nights and weekends" into a framework you can
+build a business on.
+
+### ► [Sponsor FletBox on GitHub](https://github.com/sponsors/kuko53348) ◄
+
+</div>
+
+| 💎 Sponsor tier | What you get |
+|---|---|
+| ☕ **$3 / mo** — Coffee | My thanks + the good karma of keeping open source free |
+| 🚀 **$10 / mo** — Supporter | Shout-out in the Sponsors wall + priority on issue replies |
+| 🏢 **$50 / mo** — Backer | Your name/logo in this README & docs + feature-request voting |
+| 🤝 **Custom** — Partner | Logo + link, priority support, and a say in the roadmap — [email me](mailto:kuko53348@gmail.com) |
+
+Your sponsorship funds **new widgets, the full docs book, test coverage, the mobile toolchain, and the time to ship it all.** One-time contributions welcome on the [sponsorship page](https://github.com/sponsors/kuko53348).
+
+### Other ways to support
+
+- 💳 **Crypto** (Polygon / MATIC-POL): `0x6d437bB66af8d2c44670eA18F059BE1417Dcd7bA`
+- 💼 **Commercial support, consulting, or priority help:** [kuko53348@gmail.com](mailto:kuko53348@gmail.com)
+- ▶ **Subscribe on YouTube:** [@flet-box](https://www.youtube.com/@flet-box)
+- ⭐ **Star the repo** and tell a colleague — visibility is free and it helps enormously
+
+<sub>Living in Cuba makes platforms like Mastercard hard to access, so crypto support is especially valuable. Every contribution — a sponsor tier, a donation, a star, or spreading the word — keeps FletBox growing. Thank you. 🙏</sub>
+
+### ❤️ Our sponsors
+
+<!-- Add sponsor logos/links here as they come in. Example:
+<a href="https://github.com/their-username"><img src="https://github.com/their-username.png" width="60" height="60" alt="@their-username"></a>
+-->
+
+<div align="center">
+
+_This space is empty — **be the first!**_
+
+<a href="https://github.com/sponsors/kuko53348">
+  <img src="https://img.shields.io/badge/Your_name_here-Sponsor_FletBox-ff69b4?style=for-the-badge" alt="Your name here">
+</a>
+
+</div>
+
+## License
+
+MIT — free to use, modify, redistribute, and build commercial products with.
+See [LICENSE](LICENSE). Copyright (c) 2026 Maenys Javier Quesada Reyes.

package/bin/cli.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+
+/**
+ * @file bin/cli.js
+ * @description FletBox CLI entry point with hot reload support.
+ *
+ * Parses process.argv, sets up the global Ctrl+C handler, and dispatches
+ * to the appropriate command handler.  All commands are lazy-imported so
+ * startup stays fast even on slow disks.
+ */
+
+import { createRequire } from "module";
+import fs from "fs";
+import path from "path";
+import { createProject } from "./commands/create.js";
+import { packageManager } from "./commands/package.js";
+import { createBundle } from "./commands/createBundle.js";
+import { buildAndroid } from "./commands/buildAndroid.js";
+import { buildIOS } from "./commands/buildIOS.js";
+import { runNative } from "./commands/runNative.js";
+import { runDevServer } from "./commands/runServer.js";
+import { createScreen } from "./commands/createScreen.js";
+import { createComponent } from "./commands/createComponent.js";
+import { killServer } from "./commands/killServer.js";
+import { runBundle } from "./commands/runBundle.js";
+import { runCloudflareDemo } from "./commands/runCloudflare.js";
+import { release } from "./commands/release.js";
+import { c, gradient, section, banner, divider, width, setupCtrlC } from "./utils/colors.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+// Register the global Ctrl+C handler early so every command benefits from it.
+setupCtrlC();
+
+const args = process.argv.slice(2);
+const command = args[0];
+const projectName = args[1];
+
+// Clear the terminal only when attached to an interactive session to avoid
+// polluting piped output (e.g. CI logs).
+if (process.stdout.isTTY) {
+  console.clear();
+}
+
+/**
+ * Prints the full help message, including all available commands and options.
+ * Rendered with gradient colors when the terminal supports truecolor.
+ *
+ * @returns {void}
+ */
+const showHelp = () => {
+  const cmd = (name, desc, alias = "") =>
+    `  ${c("bold", gradient(name, "#22d3ee", "#6366f1"))}${" ".repeat(Math.max(1, 22 - width(name)))}${c("gray", desc)}${alias ? c("dim", "  (" + alias + ")") : ""}`;
+
+  const opt = (name, desc) =>
+    `  ${c("brightCyan", name)}${" ".repeat(Math.max(1, 24 - name.length))}${c("gray", desc)}`;
+
+  console.log(`
+${banner("🚀 FletBox CLI", `v${version}`)}
+
+${section("🧭", "COMMANDS")}
+${cmd("create <name>", "Create a new project")}
+${cmd("create --adaptive", "responsive (mobile + desktop)")}
+${cmd("create --blank", "empty project")}
+${cmd("create --full", "AppBar+Drawer+BottomNav")}
+${cmd("create --sidebar", "desktop (Sidebar+AppBar)")}
+${cmd("create --repo <user/repo>", "set GitHub repo for OTA updates")}
+${cmd("screen <name|num>", "Create screen(s) (1-10)")}
+${cmd("component <name|num>", "Create component(s) (1-10)")}
+${cmd("createBundle [dir]", "Unified production bundle")}
+${cmd("   └─ [dir]", "target folder (default www)")}
+${cmd("release [--patch]", "Bump version, rebuild, tag (OTA release)")}
+${cmd("   └─ --minor|--major", "bump that position instead of patch")}
+${cmd("   └─ --push", "push the commit + tag to origin")}
+${cmd("build android", "Build Android debug APK")}
+${cmd("build android --release", "Build unsigned release APK/AAB to sign yourself")}
+${cmd("build ios", "Build iOS Simulator app (macOS + Xcode)")}
+${cmd("build ios --archive", "Build unsigned device archive (.xcarchive)")}
+${cmd("run-native <android|ios>", "Compile & launch on emulator/device")}
+${cmd("   └─ --device", "use a physical device instead (alias: rn)")}
+${cmd("   └─ --livereload", "hot reload on the device")}
+${cmd("run", "Static file server")}
+${cmd("run --hot", "Dev server with hot reload")}
+${cmd("run-spa", "SPA + hot reload")}
+${cmd("cloudflare", "Serve demo on a public Cloudflare HTTPS tunnel")}
+${cmd("   └─ alias", "cf | demo | tunnel")}
+${cmd("run-bundle [dir]", "Build & serve the bundle (single app.js)")}
+${cmd("pkg", "Open the package manager")}
+${cmd("kill-server [port]", "Kill servers on a port")}
+${cmd("--version | --help", "Version and this help")}
+
+${section("⚙️", "OPTIONS")}
+${opt("--port <n>, -p <n>", "Port (default 8000) — asked if not provided")}
+${opt("--hot", "Hot reload with run")}
+${opt("--quiet", "No request logging")}
+${opt("--dry-run | --list", "kill-server: just list, do not kill")}
+
+${section("✨", "EXAMPLES")}
+  ${c("gray", "flet-box create my-app --adaptive")}
+  ${c("gray", "flet-box build android        # create a debug APK")}
+  ${c("gray", "flet-box build android --release --aab  # unsigned .aab for Play")}
+  ${c("gray", "flet-box build ios            # create an iOS Simulator app")}
+  ${c("gray", "flet-box build ios --archive  # create an .xcarchive to sign in Xcode")}
+  ${c("gray", "flet-box run-native android    # build & launch on an emulator")}
+  ${c("gray", "flet-box run-native ios --device --livereload  # hot reload on iPhone")}
+  ${c("gray", "cd my-app && flet-box run-spa")}
+  ${c("gray", "flet-box run-bundle            # build & preview production")}
+  ${c("gray", "flet-box cloudflare            # public HTTPS demo link in console")}
+  ${c("gray", "flet-box kill-server 8000      # kill the parasite server")}
+
+${divider("", "#3730a3")}
+${c("dim", "  FletBox — ultra-light vanilla-JS UI framework")}
+`);
+};
+
+/**
+ * Parses the CLI flags from `process.argv`.
+ *
+ * Recognised flags:
+ * - `--port <n>` / `-p <n>` — override the default port (8000).
+ * - `--quiet`               — suppress per-request HTTP logging.
+ * - `--hot` / `--hot-reload`— enable hot-module-replacement.
+ * - `--dry-run` / `--list` / `--check` — list-only mode for `kill-server`.
+ *
+ * Invalid port values produce a warning and fall back to the default.
+ *
+ * @returns {{ port: number, portExplicit: boolean, logRequests: boolean, hot: boolean, dryRun: boolean }}
+ */
+const parseFlags = () => {
+  const flags = {
+    port: 8000,
+    portExplicit: false,
+    logRequests: true,
+    hot: false,
+    dryRun: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if ((arg === "--port" || arg === "-p") && args[i + 1]) {
+      const p = Number(args[i + 1]);
+      if (Number.isInteger(p) && p > 0 && p < 65536) {
+        flags.port = p;
+        flags.portExplicit = true;
+      } else {
+        console.warn(
+          c("yellow", `⚠️ Invalid port "${args[i + 1]}", using ${flags.port}`),
+        );
+      }
+      i++;
+    } else if (arg === "--quiet") {
+      flags.logRequests = false;
+    } else if (arg === "--hot" || arg === "--hot-reload") {
+      flags.hot = true;
+    } else if (arg === "--dry-run" || arg === "--list" || arg === "--check") {
+      flags.dryRun = true;
+    }
+  }
+
+  return flags;
+};
+
+/**
+ * Guards commands that must run inside a FletBox project directory.
+ * Exits with a descriptive error when `src/app.js` is not found in the
+ * current working directory — this prevents confusing failures later.
+ *
+ * @returns {void}
+ */
+const ensureProject = () => {
+  const inProject = fs.existsSync(path.join(process.cwd(), "src", "app.js"));
+  if (!inProject) {
+    console.error(c("red", "❌ Not inside a FletBox project"));
+    console.log(
+      c(
+        "gray",
+        "Run this inside a project folder with src/app.js (create one with: flet-box create <name>)",
+      ),
+    );
+    process.exit(1);
+  }
+};
+
+/**
+ * Main async entry point.  Parses flags, then delegates to the matching
+ * command handler via a `switch` on the first positional argument.
+ *
+ * Unrecognised commands print the help message and exit with code 1.
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+async function main() {
+  try {
+    const flags = parseFlags();
+
+    switch (command) {
+      case "create":
+      case "new":
+        if (!projectName) {
+          console.error(c("red", "❌ Error: Project name required"));
+          console.log(
+            c(
+              "gray",
+              "Usage: flet-box create <project-name> [--adaptive|--blank|--full|--sidebar|--repo user/repo]",
+            ),
+          );
+          process.exit(1);
+        }
+        if (!/^[a-z0-9-]+$/i.test(projectName)) {
+          console.error(
+            c(
+              "red",
+              "❌ Error: Invalid project name. Use only letters, numbers, and hyphens.",
+            ),
+          );
+          process.exit(1);
+        }
+        // Forward all remaining args (template flags like --adaptive) to createProject.
+        await createProject(projectName, args.slice(2));
+        break;
+
+      case "screen":
+      case "screens": {
+        ensureProject();
+        const screenInput = args[1];
+        if (!screenInput) {
+          console.error(c("red", "❌ Error: Screen name or number required"));
+          console.log(c("gray", "Usage: flet-box screen <name>"));
+          console.log(c("gray", "       flet-box screen <number> (1-10)"));
+          process.exit(1);
+        }
+        await createScreen(screenInput);
+        break;
+      }
+
+      case "component":
+      case "comp": {
+        ensureProject();
+        const componentInput = args[1];
+        if (!componentInput) {
+          console.error(
+            c("red", "❌ Error: Component name or number required"),
+          );
+          console.log(c("gray", "Usage: flet-box component <name>"));
+          console.log(c("gray", "       flet-box component <number> (1-10)"));
+          process.exit(1);
+        }
+        await createComponent(componentInput);
+        break;
+      }
+
+      case "createBundle":
+      case "bundle":
+        await createBundle(args[1]);
+        break;
+
+      case "release":
+        ensureProject();
+        await release(args.slice(1));
+        break;
+
+      case "build":
+        if (args[1] === "android") {
+          buildAndroid(args.slice(2));
+        } else if (args[1] === "ios") {
+          buildIOS(args.slice(2));
+        } else {
+          await createBundle(args[1]);
+        }
+        break;
+
+      case "run-native":
+      case "runNative":
+      case "rn":
+        runNative(args.slice(1));
+        break;
+
+      case "pkg":
+      case "package":
+      case "manager":
+        await packageManager();
+        break;
+
+      case "kill-server":
+      case "kill":
+      case "killServer":
+      case "killsrv":
+        await killServer(
+          args[1] && /^\d+$/.test(args[1]) ? args[1] : flags.port,
+          { dryRun: flags.dryRun },
+        );
+        break;
+
+      case "run":
+      case "dev":
+      case "serve":
+        ensureProject();
+        if (args[1] === "android" || args[1] === "ios") {
+          console.log(
+            c(
+              "dim",
+              `ℹ️ \`flet-box run ${args[1]}\` launches the native app — see \`flet-box run-native ${args[1]}\`.`,
+            ),
+          );
+          runNative(args.slice(1));
+          break;
+        }
+        await runDevServer({
+          spaMode: false,
+          hotReload: flags.hot,
+          port: flags.port,
+          askPort: !flags.portExplicit,
+          logRequests: flags.logRequests,
+        });
+        break;
+
+      case "run-bundle":
+      case "runBundle":
+      case "preview": {
+        ensureProject();
+        // Accept an explicit target directory as the second argument, but reject
+        // anything that looks like a flag (starts with "-") to avoid misparses.
+        const targetDir =
+          args[1] &&
+          /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(args[1]) &&
+          !args[1].startsWith("-")
+            ? args[1]
+            : "www";
+        await runBundle({
+          target: targetDir,
+          port: flags.port,
+          askPort: !flags.portExplicit,
+          logRequests: flags.logRequests,
+        });
+        break;
+      }
+
+      case "run-spa":
+      case "runSpa":
+      case "spa":
+        ensureProject();
+        await runDevServer({
+          spaMode: true,
+          hotReload: true,
+          port: flags.port,
+          askPort: !flags.portExplicit,
+          logRequests: flags.logRequests,
+        });
+        break;
+
+      case "cloudflare":
+      case "cf":
+      case "demo":
+      case "tunnel":
+        ensureProject();
+        await runCloudflareDemo({
+          port: flags.port,
+          logRequests: flags.logRequests,
+        });
+        break;
+
+      case "--version":
+      case "-v":
+        console.log(`flet-box v${version}`);
+        break;
+
+      case "--help":
+      case "-h":
+      case "help":
+        showHelp();
+        break;
+
+      default:
+        if (command) {
+          console.error(c("red", `❌ Unknown command: ${command}`));
+          console.log("");
+          showHelp();
+        } else {
+          showHelp();
+        }
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(c("red", "❌ CLI Error:"), error.message);
+    // Show the full stack trace only when DEBUG is set, to keep normal output clean.
+    if (process.env.DEBUG) console.error(error);
+    process.exit(1);
+  }
+}
+
+main();