@firesmasher/velox.js 1.0.0

package/docs/SYNTAXES.md

@@ -0,0 +1,335 @@
+# Velox.js — Syntax Reference
+
+## Statements
+
+Every Velox statement ends with `;`
+
+```
+Command("argument") $modifiers;
+```
+
+Arguments go inside `"double quotes"`. Statements without an argument still need `()`:
+
+```
+Dom.hide();
+Dom.setText("Hello");
+```
+
+---
+
+## Connecting .vlx to HTML
+
+Velox scans all `<?velox ... >` tags at page load. There are three patterns:
+
+**Pattern 1 — inline command, runs at page load:**
+```html
+<?velox Dom.setText("Hello") $target="$id(output)" >
+```
+
+**Pattern 2 — run a .vlx file at page load:**
+```html
+<?velox Velox.run("assets/scripts/velox/myscript.vlx") $target="$id(output)" >
+```
+
+**Pattern 3 — event listener (runs on user interaction):**
+```html
+<?velox $on click "$id(myBtn)": Dom.setText("Clicked!") $target="$id(output)" >
+<?velox $on click "$id(myBtn)": Velox.run("myscript.vlx") $target="$id(output)" >
+```
+
+> `velox.js` must be loaded **before** the closing `</body>` tag.
+
+---
+
+## Target Selectors
+
+Used in `$target="..."` and `$on` event selectors.
+
+| Syntax | Resolves to |
+|---|---|
+| `$id(myId)` | `document.getElementById("myId")` |
+| `$class(myClass)` | first element with that class |
+| `$query(.card > p)` | `document.querySelector(...)` — any CSS selector |
+| `$tag(div)` | first element of that tag |
+
+---
+
+## Modifiers
+
+Modifiers go after the command call on the same statement.
+
+### `$target="selector"`
+Set which element the command operates on.
+```
+Dom.setText("Hello") $target="$id(output)";
+```
+
+### `$type="value"`
+Changes the behaviour of certain commands.
+```
+Url.fetch("file.zip") $type="download";
+file.localFetch("data.json") $type="download";
+```
+
+### `$delay N`
+Wait N milliseconds before running.
+```
+Dom.show() $target="$id(box)" $delay 500;
+```
+
+### `$repeat N`
+Run the command N times (combined with `$delay` for intervals).
+```
+echo("tick") $repeat 5 $delay 1000;
+```
+
+---
+
+## Conditional Blocks
+
+Conditionals go after the command and fire based on whether it succeeded.
+
+```
+Command("arg")
+  $if .: echo("success")
+  $else: echo.err("failed");
+```
+
+| Block | Fires when |
+|---|---|
+| `$if .` | command succeeded (result is true) |
+| `$if 1` | always fires |
+| `$if 0` | never fires |
+| `$if else .` | previous `$if` did not fire, and result is true |
+| `$else` | previous `$if` / `$if else` did not fire |
+
+Callbacks inside `$if` / `$else` support: `echo()`, `echo.err()`, `echo.warn()`, `Dom.*`, `Anim.*`, `Page.redirect()`, `Page.reload()`, `Page.scrollTop()`, `Var.set()`.
+
+---
+
+## Event Listeners — `$on`
+
+```
+$on <event> "<selector>": <command>;
+```
+
+Only usable inside `<?velox ... >` tags or as top-level statements in a `.vlx` file.
+
+```
+$on click "$id(btn)": Dom.setText("Clicked") $target="$id(out)";
+$on hover "$id(card)": Anim.pulse() $target="$id(card)";
+$on input "$id(search)": Dom.getValue() $target="$id(search)";
+$on submit "$id(myForm)": Form.serialize("$id(myForm)") $target="$id(out)";
+```
+
+| Event | DOM event |
+|---|---|
+| `click` | `click` |
+| `hover` | `mouseenter` |
+| `input` | `input` |
+| `change` | `change` |
+| `submit` | `submit` (also calls `preventDefault`) |
+| `keydown` | `keydown` |
+| `load` | `window load` |
+
+---
+
+## Value Rules
+
+| Value | Meaning |
+|---|---|
+| `1` | true |
+| `0` | false |
+| `.` | pass / null / use result |
+| `_` | same as `.` |
+
+---
+
+## Path Rules
+
+| Path format | Resolves to |
+|---|---|
+| `https://example.com/x` | used as-is |
+| `/assets/file.js` | absolute from server root |
+| `../../assets/file.js` | converted to `/assets/file.js` |
+| `@env:myKey` | looked up in `quickPaths.json` |
+
+---
+
+## .vlx File Format
+
+```vlx
+// This is a comment
+
+Dom.setText("Hello") $target="$id(output)";
+Dom.addClass("active") $target="$id(output)";
+
+Var.set("user:Alice");
+Var.get("user") $target="$id(name)"
+  $if .: echo("Got it")
+  $else: echo.err("Missing");
+
+echo("Script done");
+```
+
+- One statement per line is recommended but not required
+- Statements end with `;`
+- Line comments use `//`
+- No commas between statements
+- Arguments always use `"double quotes"`
+
+---
+
+## Commands
+
+### DOM
+
+```
+Dom.setText("text")          — set textContent of target
+Dom.setHtml("html")          — set innerHTML of target
+Dom.append("html")           — append HTML inside target
+Dom.prepend("html")          — prepend HTML inside target
+Dom.remove()                 — remove target from DOM
+Dom.clear()                  — clear innerHTML of target
+Dom.show()                   — remove display:none
+Dom.hide()                   — set display:none
+Dom.toggle()                 — toggle visibility
+Dom.addClass("name")         — add CSS class
+Dom.removeClass("name")      — remove CSS class
+Dom.toggleClass("name")      — toggle CSS class
+Dom.setAttr("attr:value")    — set HTML attribute
+Dom.removeAttr("attr")       — remove HTML attribute
+Dom.setStyle("prop:value")   — set inline CSS property
+Dom.focus()                  — focus element
+Dom.click()                  — trigger click on element
+Dom.scrollTo()               — scroll element into view
+Dom.getValue()               — log input value (console)
+Dom.setValue("val")          — set input value
+```
+
+### Animation
+
+```
+Anim.fadeIn("300")           — fade in over N ms
+Anim.fadeOut("300")          — fade out over N ms
+Anim.slide("down:300")       — slide open over N ms
+Anim.slide("up:300")         — slide close over N ms
+Anim.shake()                 — shake element
+Anim.pulse("600")            — pulse element over N ms
+```
+
+### Events
+
+```
+$on click "$id(btn)": Dom.show() $target="$id(box)";
+$on hover "$id(btn)": Anim.pulse() $target="$id(btn)";
+$on input "$id(inp)": Dom.getValue() $target="$id(inp)";
+$on change "$id(sel)": echo("changed");
+$on submit "$id(frm)": Form.serialize("$id(frm)");
+$on keydown "$id(inp)": echo("key pressed");
+```
+
+### Form
+
+```
+Form.getValue("$id(inp)")        — log input value
+Form.setValue("$id(inp):value")  — set input value
+Form.clear("$id(frm)")           — clear all inputs in form
+Form.serialize("$id(frm)")       — log form as JSON, insert into target
+```
+
+### Local Storage
+
+```
+Store.set("key:value")       — set item
+Store.get("key")             — get item, insert into target
+Store.remove("key")          — remove item
+Store.clear()                — clear all
+```
+
+### Cookies
+
+```
+Cookie.set("key:value")      — set cookie (365 day expiry)
+Cookie.get("key")            — get cookie, insert into target
+Cookie.remove("key")         — expire cookie
+```
+
+### Variables (in-memory)
+
+```
+Var.set("key:value")         — store variable for this session
+Var.get("key")               — get variable, insert into target
+Var.clear("key")             — delete one variable
+Var.clear("*")               — delete all variables
+```
+
+### Network
+
+```
+Url.get("https://...")               — fetch text, insert into target
+Url.getJson("https://...")           — fetch JSON, insert pretty-printed into target
+Url.post("https://...")              — POST request
+Url.postJson("https://...:body")     — POST with JSON body
+Url.fetch("https://...")             — generic fetch
+Url.fetch("https://...") $type="download"  — download file
+iframe.Url("https://...")            — load URL in iframe inside target
+```
+
+### File
+
+```
+file.localFetch("/path/to/file")              — fetch local file
+file.localFetch("/path/to/file") $type="download"  — download local file
+```
+
+### Page
+
+```
+Page.redirect("https://...")    — navigate to URL
+Page.reload()                   — reload page
+Page.title("My Page")           — set document.title
+Page.meta("description:text")   — set/update <meta name="...">
+Page.scrollTop()                — scroll window to top
+```
+
+### Router (SPA)
+
+```
+Router.define("/:vlxPath")      — register route → .vlx file
+Router.go("/about")             — navigate to route
+Router.start() $target="$id(outlet)"  — start hash router, render into target
+```
+
+### Template
+
+Requires a `<template id="tplId">` tag in your HTML with `{{key}}` placeholders.
+
+```
+Template.render("tplId:{\"name\":\"Alice\",\"role\":\"Admin\"}")
+  $target="$id(output)";
+```
+
+### Script / Style
+
+```
+Script.load("/assets/scripts/javascript/lib.js");
+Style.load("/assets/css/theme.css");
+```
+
+### Logging
+
+```
+echo("message")        — console.log
+echo.warn("message")   — console.warn
+echo.err("message")    — console.error
+```
+
+### Velox.run
+
+Runs a `.vlx` file. Used inside `<?velox >` tags or `$on` event callbacks.
+
+```html
+<?velox Velox.run("assets/scripts/velox/myscript.vlx") $target="$id(output)" >
+<?velox $on click "$id(btn)": Velox.run("myscript.vlx") $target="$id(out)" >
+```

package/lib/cli.js

@@ -0,0 +1,90 @@
+import prompts from "prompts";
+import kleur from "kleur";
+import fs from "fs";
+import path from "path";
+import { scaffold } from "./scaffold.js";
+
+const BANNER = `
+${kleur.cyan().bold("  ██╗   ██╗███████╗██╗      ██████╗ ██╗  ██╗")}
+${kleur.cyan().bold("  ██║   ██║██╔════╝██║     ██╔═══██╗╚██╗██╔╝")}
+${kleur.cyan().bold("  ██║   ██║█████╗  ██║     ██║   ██║ ╚███╔╝ ")}
+${kleur.cyan().bold("  ╚██╗ ██╔╝██╔══╝  ██║     ██║   ██║ ██╔██╗ ")}
+${kleur.cyan().bold("   ╚████╔╝ ███████╗███████╗╚██████╔╝██╔╝ ██╗")}
+${kleur.cyan().bold("    ╚═══╝  ╚══════╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝")}
+${kleur.gray("  Velox.js — The Fast Frontend Framework")}
+`;
+
+export async function run() {
+  console.log(BANNER);
+
+  // Get project name from CLI arg or prompt
+  const argName = process.argv[2];
+
+  let projectName = argName && !argName.startsWith("-") ? argName : null;
+
+  const answers = await prompts(
+    [
+      {
+        type: projectName ? null : "text",
+        name: "projectName",
+        message: "Project name:",
+        initial: "my-velox-app",
+        validate: (v) =>
+          /^[a-z0-9\-_]+$/i.test(v) || "Use only letters, numbers, hyphens, or underscores",
+      },
+      {
+        type: "text",
+        name: "author",
+        message: "Author:",
+        initial: "",
+      },
+      {
+        type: "text",
+        name: "version",
+        message: "Version:",
+        initial: "1.0.0",
+        validate: (v) =>
+          /^\d+\.\d+\.\d+$/.test(v) || "Use semantic versioning (e.g. 1.0.0)",
+      },
+      {
+        type: "select",
+        name: "defaultPage",
+        message: "Include a starter index.html?",
+        choices: [
+          { title: "Yes", value: true },
+          { title: "No — empty project", value: false },
+        ],
+      },
+    ],
+    {
+      onCancel: () => {
+        console.log(kleur.red("\n✖ Cancelled."));
+        process.exit(1);
+      },
+    }
+  );
+
+  if (projectName) answers.projectName = projectName;
+
+  const targetDir = path.resolve(process.cwd(), answers.projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.log(
+      kleur.red(`\n✖ Directory "${answers.projectName}" already exists.`)
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `\n${kleur.cyan("◆")} Scaffolding ${kleur.bold(answers.projectName)}...\n`
+  );
+
+  await scaffold(targetDir, answers);
+
+  console.log(`${kleur.green("✔")} Done!\n`);
+  console.log(`  ${kleur.gray("cd")} ${kleur.cyan(answers.projectName)}`);
+  console.log(`  ${kleur.gray("Open")} ${kleur.cyan("public/index.html")} ${kleur.gray("to get started")}\n`);
+  console.log(
+    `  ${kleur.gray("Docs:")} ${kleur.underline("https://veloxjs.dev")}\n`
+  );
+}

package/lib/scaffold.js

@@ -0,0 +1,102 @@
+import fs from "fs";
+import path from "path";
+import kleur from "kleur";
+import { templates } from "./templates.js";
+
+const STRUCTURE = [
+  "docs",
+  "public",
+  "assets/css",
+  "assets/scripts/javascript",
+  "assets/scripts/velox",
+  "assets/icons/svg",
+  "assets/icons/png",
+  ".velox/conf",
+  "tags/savedFiles",
+  "tags/json",
+  "storage/variables",
+  "storage/env",
+];
+
+const FILES = [
+  {
+    path: ".velox/conf/config.jsonc",
+    content: (a) => templates.config(a),
+  },
+  {
+    path: "storage/env/quickPaths.json",
+    content: () => templates.quickPaths(),
+  },
+  {
+    path: "storage/variables/normal.json",
+    content: () => `{}`,
+  },
+  {
+    path: "storage/variables/sha1.json",
+    content: () => `{}`,
+  },
+  {
+    path: "tags/json/UrlS.json",
+    content: () => templates.urlS(),
+  },
+  {
+    path: "assets/css/style.css",
+    content: (a) => templates.css(a),
+  },
+  {
+    path: "assets/scripts/velox/velox.js",
+    content: () => templates.veloxRuntime(),
+  },
+  {
+    path: "tags/savedFiles/.gitkeep",
+    content: () => "",
+  },
+  {
+    path: ".gitignore",
+    content: () => templates.gitignore(),
+  },
+  {
+    path: "velox.project.json",
+    content: (a) => templates.projectMeta(a),
+  },
+  {
+    path: "docs/README.md",
+    content: () => fs.readFileSync(new URL("../docs/README.md", import.meta.url), "utf8"),
+  },
+  {
+    path: "docs/SYNTAXES.md",
+    content: () => fs.readFileSync(new URL("../docs/SYNTAXES.md", import.meta.url), "utf8"),
+  },
+  {
+    path: "docs/GUIDE.md",
+    content: () => fs.readFileSync(new URL("../docs/GUIDE.md", import.meta.url), "utf8"),
+  },
+];
+
+export async function scaffold(targetDir, answers) {
+  for (const dir of STRUCTURE) {
+    const full = path.join(targetDir, dir);
+    fs.mkdirSync(full, { recursive: true });
+    logCreated("dir", dir);
+  }
+
+  for (const file of FILES) {
+    const full = path.join(targetDir, file.path);
+    fs.writeFileSync(full, file.content(answers), "utf8");
+    logCreated("file", file.path);
+  }
+
+  if (answers.defaultPage) {
+    const indexPath = path.join(targetDir, "public/index.html");
+    fs.writeFileSync(indexPath, templates.indexHtml(answers), "utf8");
+    logCreated("file", "public/index.html");
+  } else {
+    fs.writeFileSync(path.join(targetDir, "public/.gitkeep"), "", "utf8");
+    logCreated("file", "public/.gitkeep");
+  }
+}
+
+function logCreated(type, filePath) {
+  const icon = type === "dir" ? kleur.blue("  ▸ dir ") : kleur.green("  ✔ file");
+  console.log(`${icon}  ${kleur.gray(filePath)}`);
+}