jops-core 1.0.0

package/README.md

@@ -0,0 +1,297 @@
+# JOPS — JavaScript OOP SPA Framework
+
+A no-bundler, vanilla-JavaScript SPA framework for developers who think in OOP and native-mobile patterns.
+
+## What is JOPS?
+
+JOPS is a lightweight SPA framework built on native ES6 modules. It discards the complexity of modern build toolchains while keeping a structured, class-based architecture inspired by Android's view and lifecycle model.
+
+No Webpack. No Babel. No compiler. Just `<script type="module">` and a browser.
+
+## Where JOPS Fits
+
+|           | No Bundler    | OOP Classes | Declarative View Nesting | No Element Registration |
+| --------- | ------------- | ----------- | ------------------------ | ------------------------------ |
+| **JOPS**  | ✅            | ✅          | ✅                       | ✅                             |
+| Lit       | ✅            | ✅          | ⚠️ Web Components only   | ❌                             |
+| Stimulus  | ✅            | ✅          | ❌                       | ✅                             |
+| Alpine.js | ✅            | ❌          | ❌                       | ✅                             |
+| Angular   | ❌            | ✅          | ✅                       | ✅                             |
+| Svelte    | ❌ (compiler) | ✅          | ✅                       | ✅                             |
+
+**Target audience:** Teams building internal tools, dashboards, embedded WebViews, or native mobile hybrid apps who want a structured, class-based frontend architecture without the npm/webpack/babel ecosystem overhead.
+
+---
+
+## Installation
+
+### CDN
+
+The fastest way to get started. Add these two tags to any HTML page:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "jops-core": "https://cdn.ui-db.com/jops-core/1.0.0/jops-core.min.js"
+  }
+}
+</script>
+<script src="https://cdn.ui-db.com/jops-core/1.0.0/jops-core.min.js" data-app="/src/App.js"></script>
+```
+
+The import map lets your app modules use `import { View } from "jops-core"`. The script tag bootstraps the app entry point specified in `data-app`.
+
+`App.js` is your entry point — a file you provide that instantiates your root `View` and mounts it to the page. Point `data-app` to wherever you place it.
+
+Replace `1.0.0` with the version you want to pin. No build step, no npm, no bundler.
+
+### npm
+
+For greenfield projects that want local tooling and scaffolding:
+
+```bash
+npm init -y
+npm install jops-core
+npx jops-core init
+```
+
+`npx jops-core init` vendors the library to `/lib/jops-core.min.js`, configures `index.html` with the import map, and injects build and postinstall scripts into `package.json`.
+
+### Build for production
+
+```bash
+npm run build
+```
+
+Generates a clean `dist/` folder ready to serve.
+
+### VS Code — HTML highlighting in layout templates
+
+Install the [lit-html](https://marketplace.visualstudio.com/items?itemName=bierner.lit-html) extension, then add this to your `.vscode/settings.json`:
+
+```json
+{
+  "lit-html.tags": ["layout"],
+  "editor.tokenColorCustomizations": {
+    "textMateRules": [
+      {
+        "scope": "invalid.illegal.unrecognized-tag.html",
+        "settings": { "foreground": "#569CD6" }
+      }
+    ]
+  }
+}
+```
+
+This gives you HTML syntax highlighting, Emmet, and autocomplete inside every `` layout`...` `` tagged template. Custom view tags (e.g. `<MyView>`) are coloured blue like standard HTML elements instead of red. `npx jops-core init` configures this automatically.
+
+---
+
+## Class Reference
+
+### `View` — Base Class
+
+The foundational building block. Every screen, component, and sub-component extends `View`.
+
+```js
+import { View } from "jops-core";
+
+export default class MyView extends View { ... }
+```
+
+#### Lifecycle (called by the framework in order)
+
+| Method                    | When called                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `async loadLayout(path?)` | Override to load a layout `.js` module                                         |
+| `inflate()`               | Converts `this.layout` string into `this.domNode`                              |
+| `async onLayout()`        | DOM is live — add subviews, read initial data                                  |
+| `async onResume()`        | View becomes visible — called on first display and on every return navigation  |
+| `bindEvents()`            | Wires `on*` attributes on `[type="jops-event-bind"]` elements to class methods |
+| `onBackPressed()`         | Called by Router when back navigation is detected on this view                 |
+
+#### Instance Methods
+
+| Method                          | Description                                                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `get(id)`                       | Returns an `Element` wrapper for the child with the given DOM `id`                                             |
+| `setStyle(style)`               | Injects a `.css` file link or inline style tag into `<head>`, deduped                                          |
+| `addSubView(containerId, view)` | Appends `view` into the child element with `id="containerId"`, runs its full lifecycle                         |
+| `insertSubView(view, index)`    | Inserts `view` at position `index` within `this.domNode`, runs its full lifecycle                              |
+| `removeSubView(view)`           | Removes `view` from DOM and `this.subViews`, calls `view.destroy()`                                            |
+| `find(condition)`               | Depth-first search across full subview subtree; returns flat array of all views matching the predicate         |
+| `show()`                        | Restores `this.domNode` display (removes inline `display` override)                                            |
+| `hide()`                        | Sets `this.domNode` to `display: none`                                                                         |
+| `destroy()`                     | Recursively destroys subtree — calls `destroy()` on all subviews, removes `domNode` from DOM, nulls references |
+
+#### Declarative Event Binding
+
+Mark any element with `type="jops-event-bind"` and add `on*` attributes whose values are method names on the View class:
+
+```html
+<button type="jops-event-bind" onclick="onSave">Save</button>
+```
+
+```js
+onSave(event) { ... }
+```
+
+---
+
+### `Element` — DOM Accessor (returned by `View.get()`)
+
+Returned by `view.get(id)`. Wraps a single DOM element for reading and writing.
+
+| Method       | Description                                                          |
+| ------------ | -------------------------------------------------------------------- |
+| `set(value)` | Sets `innerHTML` of the element — accepts plain text or HTML strings |
+| `value()`    | Returns the current `innerHTML` of the element                       |
+
+```js
+this.get("username").set("Alice");
+const current = this.get("username").value();
+```
+
+---
+
+### `layout` — Tagged Template Function
+
+XSS-safe tagged template literal for defining HTML layouts. Dynamic values are HTML-escaped automatically. Use `raw()` to opt out for trusted HTML.
+
+```js
+import { layout, raw } from "jops-core";
+
+const html = layout`<p>${userInput}</p>`;             // escaped
+const html = layout`<p>${raw("<b>trusted</b>")}</p>`; // raw HTML
+```
+
+---
+
+### `raw(html)` — Function
+
+Wraps a trusted HTML string to bypass escaping inside a `layout` template.
+
+```js
+import { raw } from "jops-core";
+
+raw("<b>Hello</b>"); // passed through as-is inside layout``
+```
+
+---
+
+### `Router` — extends `View`
+
+Hash-based SPA router. Singleton. Declared in the layout as `<Router type="jops" animation="slide">`.
+
+#### Two Navigation Paradigms
+
+| Pattern                  | Mechanism          | Instance             | Android analogy                 |
+| ------------------------ | ------------------ | -------------------- | ------------------------------- |
+| `href="#path"`           | flat, hashchange   | pre-existing, reused | Tab navigation                  |
+| `navigate(path, Class?)` | hierarchical stack | always new instance  | `startActivity()`               |
+| `replace(path, Class?)`  | resets stack       | existing or new      | `startActivity(FLAG_CLEAR_TOP)` |
+
+#### Static Methods
+
+| Method               | Description                        |
+| -------------------- | ---------------------------------- |
+| `Router.singleton()` | Returns the single Router instance |
+
+#### Instance Methods
+
+| Method                      | Description                                                                                                                                                                                    |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigate(path, ClassDef?)` | Creates a new view instance for `path`, pushes onto the nav stack, animates forward. Updates address bar to `#path?params`. `ClassDef` required for dynamic routes not in the static route map |
+| `back()`                    | Navigates back — pops the nav stack with animation if non-empty, otherwise calls `history.back()`                                                                                              |
+| `replace(path, ClassDef?)`  | Clears the nav stack and navigates to `path`. Uses existing flat route instance if available, otherwise creates a new one from `ClassDef`                                                      |
+| `getParams()`               | Returns the current URL query params as a plain object. Works for both static (`href="#path?k=v"`) and dynamic (`navigate("/path?k=v")`) routes                                                |
+
+#### Animation
+
+Set via the `animation` attribute on the `<Router>` element:
+
+| Value              | Behaviour                                                                  |
+| ------------------ | -------------------------------------------------------------------------- |
+| `"none"` (default) | Instant switch, no animation                                               |
+| `"slide"`          | Forward: incoming slides in from right. Back: outgoing slides out to right |
+| `"fade"`           | Crossfade between outgoing and incoming                                    |
+
+Animation only occurs on `navigate()` (forward) and `back()` when the nav stack is non-empty. Flat tab switching is always instant.
+
+#### Layout Declaration
+
+```html
+<Router type="jops" animation="slide">
+  <view type="jops" src="/src/Home.js" path="/home"></view>
+  <view type="jops" src="/src/Form.js" path="/form"></view>
+</Router>
+```
+
+#### Query Params
+
+```js
+// static route with params
+<a href="#form?tab=profile">Profile</a>;
+
+// dynamic navigation with params
+Router.singleton().navigate("/detail?id=42&mode=edit", DetailView);
+
+// read params in any view's onResume()
+const { id, mode } = Router.singleton().getParams();
+```
+
+---
+
+### `Store` — Singleton State Container
+
+App-wide runtime state. No reactivity — a plain shared key-value store with dot-notation path access. Views read from Store in `onResume()` and write in event handlers.
+
+```js
+import { Store } from "jops-core";
+
+const store = Store.singleton();
+```
+
+| Method              | Description                                                            |
+| ------------------- | ---------------------------------------------------------------------- |
+| `Store.singleton()` | Returns the single Store instance, creating it on first call           |
+| `get(path)`         | Reads a value by dot-notation path, e.g. `"user.name"`                 |
+| `set(path, value)`  | Writes a value by dot-notation path; auto-creates intermediate objects |
+| `clear()`           | Resets the entire state to `{}`                                        |
+
+```js
+Store.singleton().set("user.name", "Alice");
+Store.singleton().get("user.name"); // "Alice"
+Store.singleton().set("cart.items", [1, 2, 3]);
+Store.singleton().clear();
+```
+
+---
+
+### `EventBus` — Static Pub/Sub
+
+Stateless cross-view event broadcasting. All methods are static — no instance needed.
+
+| Method                                  | Description                                                            |
+| --------------------------------------- | ---------------------------------------------------------------------- |
+| `EventBus.subscribe(event, callback)`   | Registers a listener for the named event                               |
+| `EventBus.send(event, data?)`           | Fires the named event to all subscribers with an optional data payload |
+| `EventBus.unsubscribe(event, callback)` | Removes a specific listener by reference                               |
+
+```js
+import { EventBus } from "jops-core";
+
+EventBus.subscribe("user:login", (data) => console.log(data.name));
+EventBus.send("user:login", { name: "Alice" });
+EventBus.unsubscribe("user:login", handler);
+```
+
+---
+
+## CLI
+
+| Command               | Description                                                                |
+| --------------------- | -------------------------------------------------------------------------- |
+| `npx jops-core init`  | Vendor library, configure `index.html`, inject scripts into `package.json` |
+| `npx jops-core build` | Generate production-ready `dist/` folder                                   |

package/bin/init.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import readline from "readline";
+import { fileURLToPath } from "url";
+
+const [,, command] = process.argv;
+
+if (command !== "init" && command !== "build") {
+  console.log("Usage:");
+  console.log("  npx jops-core init    — vendor library and configure index.html");
+  console.log("  npx jops-core build   — generate production-ready dist/ folder");
+  process.exit(0);
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const consumerRoot = process.cwd();
+
+function copyDir(src, dest) {
+  const SKIP = new Set(["node_modules", "dist", ".git", "package.json", "package-lock.json", ".DS_Store"]);
+  const SKIP_EXT = new Set([".md", ".tgz", ".log"]);
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    if (SKIP_EXT.has(path.extname(entry.name).toLowerCase())) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else if (!fs.existsSync(destPath)) {
+      fs.copyFileSync(srcPath, destPath);
+      console.log(`[jops-core] Created ${path.relative(consumerRoot, destPath)}`);
+    }
+  }
+}
+
+// ─── init ────────────────────────────────────────────────────────────────────
+
+if (command === "init") {
+  const indexPath = path.join(consumerRoot, "index.html");
+  const libDir = path.join(consumerRoot, "lib");
+  const vendorDest = path.join(libDir, "jops-core.min.js");
+  const vendorSrc = path.join(__dirname, "../lib/jops-core.min.js");
+
+  if (!fs.existsSync(libDir)) fs.mkdirSync(libDir);
+  fs.copyFileSync(vendorSrc, vendorDest);
+  console.log("[jops-core] Vendored jops-core.min.js → lib/jops-core.min.js");
+
+  const IMPORTMAP = `  <script type="importmap">
+    {
+      "imports": {
+        "jops-core": "/lib/jops-core.min.js"
+      }
+    }
+  </script>`;
+
+  const MODULE_SCRIPT = `  <script type="module" src="/lib/jops-core.min.js"></script>`;
+
+  const TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>JOPS App</title>
+${IMPORTMAP}
+  </head>
+  <body>
+${MODULE_SCRIPT}
+  </body>
+</html>
+`;
+
+  if (!fs.existsSync(indexPath)) {
+    fs.writeFileSync(indexPath, TEMPLATE, "utf8");
+    console.log("[jops-core] Created index.html with importmap and module script.");
+  } else {
+    let html = fs.readFileSync(indexPath, "utf8");
+    let changed = false;
+
+    const hasImportmap = /type=["']importmap["']/.test(html) && html.includes('"jops-core"');
+    if (!hasImportmap) {
+      html = html.replace("</head>", `${IMPORTMAP}\n  </head>`);
+      changed = true;
+      console.log("[jops-core] Added importmap to index.html.");
+    }
+
+    const hasModuleScript = /src=["'][^"']*jops-core\.min\.js["']/.test(html);
+    if (!hasModuleScript) {
+      html = html.replace("</body>", `${MODULE_SCRIPT}\n  </body>`);
+      changed = true;
+      console.log("[jops-core] Added module script to index.html.");
+    }
+
+    if (changed) {
+      fs.writeFileSync(indexPath, html, "utf8");
+    } else {
+      console.log("[jops-core] index.html already configured.");
+    }
+  }
+
+  // VS Code extension recommendation
+  const vscodeSettingsDir = path.join(consumerRoot, ".vscode");
+  if (!fs.existsSync(vscodeSettingsDir)) fs.mkdirSync(vscodeSettingsDir);
+
+  const extensionsJsonPath = path.join(vscodeSettingsDir, "extensions.json");
+  const extensionsJson = fs.existsSync(extensionsJsonPath)
+    ? JSON.parse(fs.readFileSync(extensionsJsonPath, "utf8"))
+    : { recommendations: [] };
+  if (!extensionsJson.recommendations.includes("bierner.lit-html")) {
+    extensionsJson.recommendations.push("bierner.lit-html");
+    fs.writeFileSync(extensionsJsonPath, JSON.stringify(extensionsJson, null, 2) + "\n", "utf8");
+  }
+
+  const settingsJsonPath = path.join(vscodeSettingsDir, "settings.json");
+  const settingsJson = fs.existsSync(settingsJsonPath)
+    ? JSON.parse(fs.readFileSync(settingsJsonPath, "utf8"))
+    : {};
+  if (!settingsJson["lit-html.tags"]?.includes("layout")) {
+    settingsJson["lit-html.tags"] = [...(settingsJson["lit-html.tags"] ?? []), "layout"];
+  }
+  const jopsTagColor = "#569CD6";
+  const rules = settingsJson["editor.tokenColorCustomizations"]?.textMateRules ?? [];
+  const hasRule = rules.some(r => r.scope === "invalid.illegal.unrecognized-tag.html");
+  if (!hasRule) {
+    settingsJson["editor.tokenColorCustomizations"] = {
+      ...settingsJson["editor.tokenColorCustomizations"],
+      textMateRules: [
+        ...rules,
+        {
+          scope: "invalid.illegal.unrecognized-tag.html",
+          settings: { foreground: jopsTagColor }
+        }
+      ]
+    };
+  }
+  fs.writeFileSync(settingsJsonPath, JSON.stringify(settingsJson, null, 2) + "\n", "utf8");
+
+  console.log("[jops-core] VS Code: install the recommended 'lit-html' extension (bierner.lit-html) for HTML highlighting inside layout`` template literals.");
+
+  // Inject scripts into consumer's package.json
+  const pkgPath = path.join(consumerRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    let changed = false;
+    if (!pkg.scripts?.build) {
+      pkg.scripts = { ...pkg.scripts, build: "npx jops-core build" };
+      changed = true;
+      console.log('[jops-core] Added "build" script to package.json.');
+    }
+    if (!pkg.scripts?.postinstall) {
+      pkg.scripts = { ...pkg.scripts, postinstall: "npx jops-core init" };
+      changed = true;
+      console.log('[jops-core] Added "postinstall" script to package.json.');
+    }
+    if (changed) fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+  }
+
+  // Template selection
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+  const choice = await ask(
+    "\nCreate JOPS project from existing templates:\n" +
+    "  1. Empty JOPS project (basic skeleton for JOPS project architecture)\n" +
+    "  2. Hello World JOPS project (an example project utilizing all features)\n" +
+    "  3. None (I'll create my own architecture)\n" +
+    "Enter choice (1-3): "
+  );
+  rl.close();
+
+  const templateSrc = path.join(__dirname, "../templates");
+  if (choice.trim() === "1") {
+    copyDir(path.join(templateSrc, "empty"), consumerRoot);
+    // Add data-app to the module script in index.html
+    let html = fs.readFileSync(indexPath, "utf8");
+    html = html.replace(
+      /(<script[^>]+src=["'][^"']*jops-core\.min\.js["'])([^>]*>)/,
+      (_, open, rest) => open.includes("data-app") ? open + rest : open + ' data-app="/src/App.js"' + rest
+    );
+    fs.writeFileSync(indexPath, html, "utf8");
+    console.log("[jops-core] Created empty JOPS project skeleton.");
+  } else if (choice.trim() === "2") {
+    copyDir(path.join(templateSrc, "hello-world"), consumerRoot);
+    let html = fs.readFileSync(indexPath, "utf8");
+    html = html.replace(
+      /(<script[^>]+src=["'][^"']*jops-core\.min\.js["'])([^>]*>)/,
+      (_, open, rest) => open.includes("data-app") ? open + rest : open + ' data-app="/src/App.js"' + rest
+    );
+    fs.writeFileSync(indexPath, html, "utf8");
+    console.log("[jops-core] Created Hello World JOPS project.");
+  } else {
+    console.log("[jops-core] No template applied. Setup complete.");
+  }
+}
+
+// ─── build ───────────────────────────────────────────────────────────────────
+
+if (command === "build") {
+  const BUILD_EXCLUDE = new Set([
+    "node_modules", "dist", ".git",
+    "package.json", "package-lock.json", ".gitignore", ".npmrc",
+  ]);
+
+  function buildCopyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      if (BUILD_EXCLUDE.has(entry.name)) continue;
+      if ([".md", ".tgz", ".log"].includes(path.extname(entry.name).toLowerCase())) continue;
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        buildCopyDir(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+
+  const distDir = path.join(consumerRoot, "dist");
+  if (fs.existsSync(distDir)) fs.rmSync(distDir, { recursive: true, force: true });
+  buildCopyDir(consumerRoot, distDir);
+  console.log("[jops-core] Built → dist/");
+}

package/lib/jops-core.min.js

@@ -0,0 +1,5 @@
+var _=Object.defineProperty;var h=(a,t)=>_(a,"name",{value:t,configurable:!0});(()=>{console.log("JOPS initialized");let a=document.currentScript?.dataset.app??"/src/App.js",t=document.createElement("script");t.type="module",t.textContent=`
+    import('${a}')
+      .then(m => new m.default())
+      .catch(err => console.error("JOPS: App.js not found or failed to load", err));
+  `,document.body.appendChild(t)})();var f=class{static{h(this,"RawHTML")}constructor(t){this.html=t}},R=h(a=>new f(a),"raw");function E(a,...t){return a.reduce((e,s,n)=>{if(n>=t.length)return e+s;let o=t[n];return o==null?e+s:o instanceof f?e+s+o.html:e+s+String(o).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")},"")}h(E,"layout");var m=class{static{h(this,"Element")}constructor(t,e){this.element=t?.id===e?t:t.querySelector(`#${e}`)}set(t){this.element.innerHTML=t}value(){return this.element.innerHTML}},p=class a{static{h(this,"View")}#t=!1;#e=!1;constructor(t){this.loadLayout(t),this.subViews=[]}async loadLayout(t){if(t)if(t.endsWith(".js"))try{let e=await import(t);this.layout=e.default}catch(e){console.error("JOPS: failed to load layout:",t,e)}else this.layout=t}setStyle(t){if(t)if(this.style=t,t.endsWith(".css")){if(document.querySelector(`link[href="${t}"]`))return;let e=document.createElement("link");e.rel="stylesheet",e.href=t,document.head.appendChild(e)}else{if(document.querySelector(`style[data-jops="${t}"]`))return;let e=document.createElement("style");e.setAttribute("data-jops",t),e.textContent=t,document.head.appendChild(e)}}get(t){return new m(this.domNode,t)}bindEvents(){if(!this.domNode)return;let t=[...this.domNode.querySelectorAll("[type='jops-event-bind']")];this.domNode.getAttribute("type")==="jops-event-bind"&&t.unshift(this.domNode);for(let e of t)for(let s of e.attributes){if(!s.name.startsWith("on"))continue;let n=s.value.trim();typeof this[n]=="function"&&(e[s.name]=o=>this[n](o))}}inflate(){if(!this.layout||this.#t)return;this.#t=!0;let t=document.createElement("template");t.innerHTML=this.layout;let s=t.content.cloneNode(!0).firstElementChild;this.domNode=s}async addSubView(t,e){this.subViews.push(e),e.domNode||(await e.loadLayout(),e.inflate()),this.domNode.querySelector(`#${t}`).appendChild(e.domNode),await e?.onLayout?.(),await e?.onResume?.(),e?.bindEvents?.()}hide(){this.domNode.style.display="none"}show(){this.domNode.style.display=""}find(t){let e=[];for(let s of this.subViews)t(s)&&e.push(s),e.push(...s.find?.(t)??[]);return e}destroy(){this.subViews.forEach(t=>t.destroy?.()),this.subViews=[],this.domNode?.remove(),this.domNode=null,this.layout=null}removeSubView(t){t.destroy?.(),this.subViews=this.subViews.filter(e=>e!==t)}async insertSubView(t,e){t.domNode||(await t.loadLayout(),t.inflate());let s=this.domNode.children[e]??null;this.domNode.insertBefore(t.domNode,s),this.subViews.splice(e,0,t),await t?.onLayout?.(),await t?.onResume?.(),t?.bindEvents?.()}async render(){if(!this.layout||this.#e)return;this.#e=!0;let t=this.domNode??document.body;t===document.body&&(t.innerHTML=this.layout);let e=Array.from(t.querySelectorAll("[type='jops']")).filter(s=>s.tagName==="ROUTER"||!s.closest("router")||s.closest("router")===t);e.length!==0&&await Promise.all(e.map(async s=>{if(s.tagName==="ROUTER"){let d=new y(s);await d.render(),await d.onLayout();return}let n=s.getAttribute("layout"),o=s.getAttribute("src");if(!o&&!n)return;let r;if(o){let l=(await import(o)).default;r=new l}else r=new a;this.subViews.push(r),await r.loadLayout(n);let i=document.createElement("template");i.innerHTML=r.layout??"";let c=i.content.cloneNode(!0);if(s.children.length>0){let d=c.firstElementChild??c;Array.from(s.children).forEach(l=>d.appendChild(l))}let u=c.firstElementChild;r.routePath=s.getAttribute("path"),s.replaceWith(c),r.domNode=u,await r.render(),await r?.onLayout?.(),await r?.onResume?.(),r?.bindEvents?.()}))}},b=class a{static{h(this,"EventBus")}static#t={};static subscribe(t,e){a.#t[t]||(a.#t[t]=[]),a.#t[t].push(e)}static send(t,e){a.#t[t]?.forEach(s=>s(e))}static unsubscribe(t,e){a.#t[t]&&(a.#t[t]=a.#t[t].filter(s=>s!==e))}},T=class a{static{h(this,"Store")}static#t=null;static singleton(){return a.#t||(a.#t=new a),a.#t}constructor(){this._state={}}get(t){return t.split(".").reduce((e,s)=>e?.[s],this._state)}set(t,e){let s=t.split("."),n=s.pop(),o=s.reduce((r,i)=>(r[i]||(r[i]={}),r[i]),this._state);o[n]=e}clear(){this._state={}}},y=class a extends p{static{h(this,"Router")}static#t=null;static singleton(){return a.#t}constructor(t){super(),a.#t=this,this.rootNode=t.parentNode,this.routerDomNode=t,this.domNode=t,this.layout=t.innerHTML,this.animation=t.getAttribute("animation")??"none"}async onLayout(){let t=document.createDocumentFragment();for(;this.routerDomNode.firstChild;)t.appendChild(this.routerDomNode.firstChild);this.routerDomNode.replaceWith(t),this.domNode=this.rootNode,this.initRouter()}initRouter(){this.routes={};for(let e of this.subViews)if(e.routePath){let s=e.routePath.slice(1).split("?")[0];this.routes[s]=e}this._navStack=[],this._baseView=null;let t=Object.keys(this.routes)[0];history.replaceState(null,"","#"+t),window.addEventListener("hashchange",()=>{let e=window.location.hash.slice(1),s=e.split("?")[0];if(!(!s||!this.routes[s])){if(this._pendingBack){this._pendingBack=!1;return}this._switchTo(e)}}),window.addEventListener("popstate",()=>{if(this._navStack.length>0){let n=this._navStack.pop(),o=this._navStack.at(-1)??this._baseView;n?.onBackPressed?.(),this._animateTransition(n,o,"back").then(()=>n.destroy());return}this._currentView?.onBackPressed?.();let e=window.location.hash.slice(1),s=e.split("?")[0];s&&this.routes[s]&&(this._pendingBack=!0,this._switchTo(e))}),this._switchTo(t)}async _animateTransition(t,e,s){this.animation==="slide"?await this._slideTransition(t,e,s):this.animation==="fade"?await this._fadeTransition(t,e):(t.domNode.hidden=!0,e.domNode.hidden=!1,this._currentView=e,e?.onResume?.())}async _slideTransition(t,e,s){let n=this.domNode,o=s==="forward",r=n.getBoundingClientRect(),i=t.domNode.getBoundingClientRect(),c=i.left-r.left,u=i.top-r.top,d=i.width,l=n.offsetWidth-c,w=`position:absolute;left:${c}px;top:${u}px;width:${d}px`;n.style.cssText=`position:relative;overflow:hidden;height:${n.offsetHeight}px`,t.domNode.style.cssText=`${w};z-index:${o?1:2}`,t.domNode.hidden=!1,e.domNode.style.cssText=`${w};z-index:${o?2:1}`,e.domNode.hidden=!1;let x=o?e.domNode:t.domNode,S=o?`${l}px`:"0px",V=o?"0px":`${l}px`,N=x.animate([{transform:`translateX(${S})`},{transform:`translateX(${V})`}],{duration:300,easing:"ease",fill:"forwards"});await N.finished,N.cancel(),t.domNode.hidden=!0,t.domNode.style.cssText="",e.domNode.style.cssText="",n.style.cssText="",this._currentView=e,e?.onResume?.()}async _fadeTransition(t,e){let s=this.domNode,n=s.getBoundingClientRect(),o=t.domNode.getBoundingClientRect(),r=o.left-n.left,i=o.top-n.top,c=o.width,u=`position:absolute;left:${r}px;top:${i}px;width:${c}px`;s.style.cssText=`position:relative;overflow:hidden;height:${s.offsetHeight}px`,t.domNode.style.cssText=u,t.domNode.hidden=!1,e.domNode.style.cssText=u,e.domNode.hidden=!1;let d=t.domNode.animate([{opacity:1},{opacity:0}],{duration:450,easing:"ease",fill:"forwards"}),l=e.domNode.animate([{opacity:0},{opacity:1}],{duration:450,easing:"ease",fill:"forwards"});await Promise.all([d.finished,l.finished]),d.cancel(),l.cancel(),t.domNode.hidden=!0,t.domNode.style.cssText="",e.domNode.style.cssText="",s.style.cssText="",this._currentView=e,e?.onResume?.()}_switchTo(t){let e=t.split("?")[0];for(let[s,n]of Object.entries(this.routes)){let o=s===e;n.domNode.hidden=!o,o&&(this._currentView=n,n?.onResume?.())}}back(){history.back()}getParams(){let t=window.location.hash.split("?")[1];return t?Object.fromEntries(new URLSearchParams(t)):{}}async navigate(t,e){let[s,n]=t.replace(/^\//,"").split("?"),o=s,r=e??this.routes[o]?.constructor;if(!r){console.error(`JOPS Router: no class found for path "${t}"`);return}this._navStack.length===0&&(this._baseView=this._currentView);let i=new r;await i.loadLayout(),i.inflate(),this.domNode.appendChild(i.domNode),history.pushState({jopsNav:!0},"","#"+o+(n?"?"+n:"")),await i.onLayout?.(),await i.onResume?.(),i.bindEvents?.(),this._navStack.push(i),this._animateTransition(this._currentView,i,"forward")}async replace(t,e){this._navStack.forEach(i=>i.destroy?.()),this._navStack=[];let[s,n]=t.replace(/^\//,"").split("?"),o=s,r="#"+o+(n?"?"+n:"");if(this.routes[o])history.replaceState(null,"",r),this._switchTo(o);else if(e){let i=new e;await i.loadLayout(),i.inflate(),this.domNode.appendChild(i.domNode),await i.onLayout?.(),await i.onResume?.(),i.bindEvents?.(),this._currentView&&(this._currentView.domNode.hidden=!0),this._currentView=i,history.replaceState(null,"",r)}else console.error(`JOPS Router: no instance or class found for path "${t}"`)}};export{b as EventBus,y as Router,T as Store,p as View,E as layout,R as raw};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "jops-core",
+  "version": "1.0.0",
+  "description": "A no-bundler, OOP-first SPA framework with Android-style view composition",
+  "type": "module",
+  "exports": "./lib/jops-core.min.js",
+  "browser": "./lib/jops-core.min.js",
+  "bin": {
+    "jops-core": "bin/init.js"
+  },
+  "files": [
+    "lib/jops-core.min.js",
+    "bin/init.js",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "esbuild src/jops-core.js --bundle --format=esm --minify --keep-names --outfile=lib/jops-core.min.js && npm pack"
+  },
+  "keywords": [
+    "spa",
+    "framework",
+    "oop",
+    "no-bundler",
+    "router",
+    "view",
+    "AI friendly SDK"
+  ],
+  "author": "arik@ui-db.com",
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "esbuild": "^0.25.12"
+  },
+  "packageManager": "npm@12.0.2+sha512.b885e890b9418fa1693544d05f53e64f9a73ec194837d4258b15fecdd692347b1dd2a517b1b0cbaf9d31cd8e92c3b70956bd2ecc72833a57b4b3098f5bfa7943"
+}

package/templates/empty/src/App.js

@@ -0,0 +1,11 @@
+import { View } from "jops-core";
+
+export default class App {
+  constructor() {
+    const root = new View();
+    (async () => {
+      await root.loadLayout("/src/layout/mainlayout.js");
+      root.render();
+    })();
+  }
+}

package/templates/empty/src/layout/mainlayout.js

@@ -0,0 +1,2 @@
+import { layout } from "jops-core";
+export default layout`<div>I'm your main layout!</div>`;

package/templates/hello-world/assets/jops-hierarchy.svg

@@ -0,0 +1,57 @@
+<svg viewBox="0 0 400 320" xmlns="http://www.w3.org/2000/svg" font-family="monospace">
+  <rect width="400" height="320" fill="#0f1117"/>
+
+  <!-- Title -->
+  <text x="200" y="30" text-anchor="middle" fill="#7c8cf8" font-size="13" font-weight="bold" letter-spacing="2">VIEW HIERARCHY</text>
+
+  <!-- Root node -->
+  <rect x="150" y="50" width="100" height="36" rx="6" fill="#1e2235" stroke="#7c8cf8" stroke-width="1.5"/>
+  <text x="200" y="73" text-anchor="middle" fill="#7c8cf8" font-size="12">App</text>
+
+  <!-- Lines to level 2 -->
+  <line x1="200" y1="86" x2="100" y2="120" stroke="#3d4466" stroke-width="1.2"/>
+  <line x1="200" y1="86" x2="200" y2="120" stroke="#3d4466" stroke-width="1.2"/>
+  <line x1="200" y1="86" x2="300" y2="120" stroke="#3d4466" stroke-width="1.2"/>
+
+  <!-- Level 2 nodes -->
+  <rect x="50" y="120" width="100" height="36" rx="6" fill="#1e2235" stroke="#56cfb2" stroke-width="1.5"/>
+  <text x="100" y="143" text-anchor="middle" fill="#56cfb2" font-size="12">Router</text>
+
+  <rect x="150" y="120" width="100" height="36" rx="6" fill="#1e2235" stroke="#56cfb2" stroke-width="1.5"/>
+  <text x="200" y="143" text-anchor="middle" fill="#56cfb2" font-size="12">Header</text>
+
+  <rect x="250" y="120" width="100" height="36" rx="6" fill="#1e2235" stroke="#56cfb2" stroke-width="1.5"/>
+  <text x="300" y="143" text-anchor="middle" fill="#56cfb2" font-size="12">Footer</text>
+
+  <!-- Lines to level 3 (from Router) -->
+  <line x1="100" y1="156" x2="60" y2="192" stroke="#3d4466" stroke-width="1.2"/>
+  <line x1="100" y1="156" x2="140" y2="192" stroke="#3d4466" stroke-width="1.2"/>
+
+  <!-- Level 3 nodes -->
+  <rect x="20" y="192" width="80" height="36" rx="6" fill="#1e2235" stroke="#f0a040" stroke-width="1.5"/>
+  <text x="60" y="215" text-anchor="middle" fill="#f0a040" font-size="11">HomeView</text>
+
+  <rect x="110" y="192" width="80" height="36" rx="6" fill="#1e2235" stroke="#f0a040" stroke-width="1.5"/>
+  <text x="150" y="215" text-anchor="middle" fill="#f0a040" font-size="11">FormView</text>
+
+  <!-- Lines to level 4 -->
+  <line x1="150" y1="228" x2="130" y2="262" stroke="#3d4466" stroke-width="1.2"/>
+  <line x1="150" y1="228" x2="170" y2="262" stroke="#3d4466" stroke-width="1.2"/>
+
+  <!-- Level 4 nodes -->
+  <rect x="100" y="262" width="60" height="30" rx="5" fill="#1e2235" stroke="#f06292" stroke-width="1.5"/>
+  <text x="130" y="282" text-anchor="middle" fill="#f06292" font-size="10">Card</text>
+
+  <rect x="170" y="262" width="60" height="30" rx="5" fill="#1e2235" stroke="#f06292" stroke-width="1.5"/>
+  <text x="200" y="282" text-anchor="middle" fill="#f06292" font-size="10">Card</text>
+
+  <!-- Legend -->
+  <rect x="270" y="200" width="10" height="10" rx="2" fill="#7c8cf8"/>
+  <text x="285" y="210" fill="#5a6080" font-size="10">App root</text>
+  <rect x="270" y="218" width="10" height="10" rx="2" fill="#56cfb2"/>
+  <text x="285" y="228" fill="#5a6080" font-size="10">View</text>
+  <rect x="270" y="236" width="10" height="10" rx="2" fill="#f0a040"/>
+  <text x="285" y="246" fill="#5a6080" font-size="10">Route</text>
+  <rect x="270" y="254" width="10" height="10" rx="2" fill="#f06292"/>
+  <text x="285" y="264" fill="#5a6080" font-size="10">SubView</text>
+</svg>