@firesmasher/velox.js 1.0.0

package/bin/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../lib/cli.js";
+run();

package/docs/GUIDE.md

@@ -0,0 +1,333 @@
+# Velox.js — Practical Guide
+
+## 1. Setting up
+
+Scaffold a new project:
+```bash
+npx velox my-app
+cd my-app
+```
+
+Serve it locally (Velox uses `fetch()` internally, so you need a server — opening `index.html` directly as a `file://` URL won't work):
+```
+npx serve .
+```
+or use VS Code Live Server.
+
+---
+
+## 2. The basic connection: .vlx → HTML
+
+This is the most important thing to understand. There are exactly three ways to connect Velox to your HTML.
+
+### Run a command at page load
+
+Put a `<?velox >` tag anywhere in your HTML body. It runs when the page loads.
+
+```html
+<div id="output"></div>
+
+<?velox Dom.setText("Page is ready") $target="$id(output)" >
+
+<script src="assets/scripts/velox/velox.js"></script>
+```
+
+### Run a .vlx file at page load
+
+```html
+<div id="output"></div>
+
+<?velox Velox.run("assets/scripts/velox/myscript.vlx") $target="$id(output)" >
+
+<script src="assets/scripts/velox/velox.js"></script>
+```
+
+### Wire a button to a command or .vlx file
+
+```html
+<button id="myBtn">Click me</button>
+<div id="output"></div>
+
+<!-- Inline command on click -->
+<?velox $on click "$id(myBtn)": Dom.setText("Clicked!") $target="$id(output)" >
+
+<!-- Or run a .vlx file on click -->
+<?velox $on click "$id(myBtn)": Velox.run("myscript.vlx") $target="$id(output)" >
+
+<script src="assets/scripts/velox/velox.js"></script>
+```
+
+> `velox.js` must always be the **last script** before `</body>`. The `<?velox >` tags can go anywhere in the body — they're read as raw HTML text, not executed as JS.
+
+---
+
+## 3. Writing .vlx files
+
+`.vlx` files live in `assets/scripts/velox/`. Each statement ends with `;`. Use `//` for comments.
+
+```vlx
+// myscript.vlx
+
+Dom.setText("Hello from the script") $target="$id(output)";
+Dom.addClass("loaded") $target="$id(output)";
+echo("Script ran");
+```
+
+**Common mistakes:**
+
+| Wrong | Right |
+|---|---|
+| `Dom.setText("Hi"), $target="..."` | `Dom.setText("Hi") $target="..."` |
+| `Velox.run("path") { $target: "..." }` | `Velox.run("path") $target="..."` (in HTML tag) |
+| `$if 0: echo("ok")` | `$if .: echo("ok")` (use `.` for "if succeeded") |
+| Separating statements with `,` | Use `;` |
+
+---
+
+## 4. Targets
+
+Every command needs to know which element to act on. You set this with `$target`.
+
+```
+$target="$id(myId)"           → <div id="myId">
+$target="$class(myClass)"     → first element with class "myClass"
+$target="$query(.card > p)"   → any CSS selector
+$target="$tag(main)"          → first <main> element
+```
+
+In a `<?velox >` tag:
+```html
+<?velox Dom.hide() $target="$id(sidebar)" >
+```
+
+In a `.vlx` file:
+```vlx
+Dom.hide() $target="$id(sidebar)";
+```
+
+---
+
+## 5. Event listeners
+
+Wire any HTML element to any command using `$on` inside a `<?velox >` tag.
+
+```html
+<!-- Click -->
+<?velox $on click "$id(btn)": Dom.setText("Clicked") $target="$id(out)" >
+
+<!-- Hover -->
+<?velox $on hover "$id(card)": Anim.pulse("400") $target="$id(card)" >
+
+<!-- Input (fires on every keystroke) -->
+<?velox $on input "$id(searchBox)": Dom.getValue() $target="$id(searchBox)" >
+
+<!-- Form submit (automatically calls preventDefault) -->
+<?velox $on submit "$id(myForm)": Form.serialize("$id(myForm)") $target="$id(out)" >
+```
+
+You can also put `$on` statements inside a `.vlx` file — useful when you want to set up multiple listeners from one script:
+
+```vlx
+// setup.vlx
+$on click "$id(btnA)": Dom.show() $target="$id(panelA)";
+$on click "$id(btnB)": Dom.show() $target="$id(panelB)";
+$on click "$id(closeBtn)": Dom.hide() $target="$id(modal)";
+```
+
+---
+
+## 6. Conditionals
+
+Check whether a command succeeded and branch on the result.
+
+```vlx
+Url.get("https://api.example.com/data") $target="$id(output)"
+  $if .: echo("Loaded!")
+  $else: echo.err("Failed to load");
+```
+
+`$if .` means "if the command succeeded". You can also use `$if 1` (always true) or `$if 0` (always false).
+
+Chain with `$if else`:
+```vlx
+Store.get("theme") $target="$id(output)"
+  $if .: echo("Theme found")
+  $if else .: echo("Using default")
+  $else: echo.err("Storage error");
+```
+
+---
+
+## 7. Variables
+
+In-memory variables (cleared on page reload):
+
+```vlx
+Var.set("username:Alice");
+Var.get("username") $target="$id(nameDisplay)";
+Var.clear("username");
+Var.clear("*");
+```
+
+Persistent variables use Local Storage:
+
+```vlx
+Store.set("theme:dark");
+Store.get("theme") $target="$id(themeLabel)";
+Store.remove("theme");
+```
+
+---
+
+## 8. Animations
+
+All animation commands target an element with `$target`.
+
+```vlx
+Anim.fadeIn("300") $target="$id(box)";
+Anim.fadeOut("300") $target="$id(box)";
+Anim.slide("down:400") $target="$id(menu)";
+Anim.slide("up:400") $target="$id(menu)";
+Anim.shake() $target="$id(errorMsg)";
+Anim.pulse("600") $target="$id(badge)";
+```
+
+A common pattern — show a hidden element with a fade:
+```html
+<div id="modal" style="display:none;">Hello!</div>
+<button id="openBtn">Open</button>
+
+<?velox $on click "$id(openBtn)": Anim.fadeIn("300") $target="$id(modal)" >
+```
+
+---
+
+## 9. Network requests
+
+Fetch text from a URL and put it in an element:
+```vlx
+Url.get("https://api.example.com/message") $target="$id(output)"
+  $if .: echo("Loaded")
+  $else: echo.err("Request failed");
+```
+
+Fetch JSON and display it:
+```vlx
+Url.getJson("https://api.example.com/user") $target="$id(output)";
+```
+
+POST a request:
+```vlx
+Url.post("https://api.example.com/action")
+  $if .: Dom.setText("Saved!") $target="$id(status)"
+  $else: Dom.setText("Error") $target="$id(status)";
+```
+
+Embed a URL in an iframe:
+```html
+<div id="frameContainer"></div>
+
+<?velox $on click "$id(loadBtn)": iframe.Url("https://example.com") $target="$id(frameContainer)" >
+```
+
+---
+
+## 10. Template rendering
+
+Define a `<template>` tag in your HTML with `{{key}}` placeholders:
+
+```html
+<template id="userCard">
+  <div class="card">
+    <h2>{{name}}</h2>
+    <p>{{role}}</p>
+  </div>
+</template>
+
+<div id="output"></div>
+```
+
+Render it with JSON data:
+```vlx
+Template.render("userCard:{\"name\":\"Alice\",\"role\":\"Admin\"}") $target="$id(output)";
+```
+
+---
+
+## 11. SPA Router
+
+Define routes that each map to a `.vlx` file. The script runs inside the outlet element when the route is active.
+
+```html
+<nav>
+  <a href="#/">Home</a>
+  <a href="#/about">About</a>
+</nav>
+<main id="app"></main>
+
+<?velox
+  Router.define("/:/pages/home.vlx");
+  Router.define("/about:/pages/about.vlx");
+  Router.start() $target="$id(app)";
+>
+```
+
+Navigate programmatically from a `.vlx` file:
+```vlx
+Router.go("/about");
+```
+
+---
+
+## 12. Path and @env
+
+Paths in `.vlx` files can be absolute (`/assets/...`), relative to root (`../../` is automatically resolved to `/`), or use environment keys:
+
+```vlx
+Url.get("@env:apiBase");
+Script.load("@env:myLib");
+```
+
+Keys are defined in `storage/env/quickPaths.json`:
+```json
+{
+  "apiBase": "https://api.example.com",
+  "myLib": "/assets/scripts/javascript/lib.js"
+}
+```
+
+---
+
+## 13. Delay and repeat
+
+```vlx
+// Wait 1 second then show
+Dom.show() $target="$id(toast)" $delay 1000;
+
+// Flash 3 times, 500ms apart
+Anim.pulse("200") $target="$id(alert)" $repeat 3 $delay 500;
+```
+
+---
+
+## 14. Loading external scripts and styles
+
+```vlx
+Script.load("/assets/scripts/javascript/chart.js")
+  $if .: echo("Chart.js ready")
+  $else: echo.err("Failed to load chart");
+
+Style.load("/assets/css/theme.css");
+```
+
+---
+
+## 15. Page utilities
+
+```vlx
+Page.title("Dashboard");
+Page.meta("description:My app description");
+Page.scrollTop();
+Page.redirect("https://example.com");
+Page.reload();
+```

package/docs/README.md

@@ -0,0 +1,140 @@
+# Velox.js
+
+**The fast frontend framework with its own scripting language.**
+
+Velox.js lets you control your HTML pages using `.vlx` script files and `<?velox >` tags — no build step, no bundler, no JSX. Just drop `velox.js` into your page and start writing scripts.
+
+---
+
+## Quick start
+
+```bash
+npx velox my-app
+cd my-app
+```
+
+Open `public/index.html` in your browser (via a local server — e.g. VS Code Live Server, or `npx serve .`).
+
+---
+
+## How it works
+
+The Velox runtime (`velox.js`) scans your HTML for `<?velox ... >` tags when the page loads. Each tag either runs a command directly or wires up an event listener.
+
+**Run a command on page load:**
+```html
+<?velox Dom.setText("Hello!") $target="$id(output)" >
+```
+
+**Run a `.vlx` script file on page load:**
+```html
+<?velox Velox.run("assets/scripts/velox/myscript.vlx") $target="$id(output)" >
+```
+
+**Wire a button click to a command:**
+```html
+<?velox $on click "$id(myBtn)": Dom.setText("Clicked!") $target="$id(output)" >
+```
+
+**Wire a button click to a `.vlx` file:**
+```html
+<?velox $on click "$id(myBtn)": Velox.run("myscript.vlx") $target="$id(output)" >
+```
+
+The runtime must be loaded before `</body>`:
+```html
+<script src="assets/scripts/velox/velox.js"></script>
+```
+
+---
+
+## .vlx scripts
+
+`.vlx` files are plain text scripts with one statement per line, separated by `;`.
+
+```vlx
+// myscript.vlx
+
+Dom.setText("Loaded from script!") $target="$id(output)";
+Dom.addClass("active") $target="$id(output)";
+Anim.fadeIn("400") $target="$id(output)";
+
+Var.set("user:Alice");
+echo("Script finished");
+```
+
+---
+
+## Project structure
+
+```
+my-app/
+├── public/
+│   └── index.html
+├── assets/
+│   ├── css/
+│   │   └── style.css
+│   └── scripts/
+│       └── velox/
+│           ├── velox.js        ← runtime
+│           └── myscript.vlx   ← your scripts go here
+├── .velox/
+│   └── conf/
+│       └── config.jsonc
+├── storage/
+│   ├── env/
+│   │   └── quickPaths.json
+│   └── variables/
+│       └── normal.json
+├── tags/
+│   └── json/
+│       └── UrlS.json
+└── velox.project.json
+```
+
+---
+
+## Selectors
+
+| Syntax | Selects |
+|---|---|
+| `$id(myId)` | `#myId` |
+| `$class(myClass)` | first `.myClass` |
+| `$query(.card > p)` | any CSS selector |
+| `$tag(div)` | first `<div>` |
+
+---
+
+## Command categories
+
+| Category | Commands |
+|---|---|
+| DOM | `setText` `setHtml` `append` `prepend` `remove` `clear` `show` `hide` `toggle` `addClass` `removeClass` `toggleClass` `setAttr` `removeAttr` `setStyle` `focus` `click` `scrollTo` `getValue` `setValue` |
+| Animation | `fadeIn` `fadeOut` `slide` `shake` `pulse` |
+| Events | `$on click` `hover` `input` `change` `submit` `keydown` `load` |
+| Form | `getValue` `setValue` `clear` `serialize` |
+| Storage | `Store.set` `get` `remove` `clear` |
+| Cookies | `Cookie.set` `get` `remove` |
+| Variables | `Var.set` `get` `clear` |
+| Network | `Url.get` `getJson` `post` `postJson` `fetch` · `iframe.Url` |
+| File | `file.localFetch` |
+| Page | `redirect` `reload` `title` `meta` `scrollTop` |
+| Router | `Router.define` `go` `start` |
+| Template | `Template.render` |
+| Script/Style | `Script.load` · `Style.load` |
+| Logging | `echo` `echo.warn` `echo.err` |
+
+See [SYNTAXES.md](./SYNTAXES.md) for the full reference.
+
+---
+
+## Requirements
+
+- Node.js >= 16 (for the CLI scaffolder)
+- A local HTTP server to serve your project (required for `fetch()` to work)
+
+---
+
+## License
+
+MIT