atmx-web 0.42.0

package/src/dom/scanner.ts

@@ -0,0 +1,125 @@
+// FILE: src/dom/scanner.ts
+import { connectQuery, executeMutation, parseRpcCall } from "./lifecycle";
+import { updateContext, getContext } from "../core/context";
+import { queryRegistry } from "../core/query";
+import { resolveRoute } from "../core/router";
+import { evaluateExpression } from "../resolver/evaluator";
+
+const intersectionObserver = new IntersectionObserver((entries) => {
+  entries.forEach((entry) => {
+    if (entry.isIntersecting) {
+      const el = entry.target as HTMLElement;
+      if (el.hasAttribute("ax-query")) connectQuery(el);
+      intersectionObserver.unobserve(el);
+    }
+  });
+});
+
+/**
+ * ✨ NEW: Evaluates dynamic prefixed attributes like :ax-query="sdk.pyExample.login()"
+ */
+function evaluateDynamicAttributes(root: HTMLElement | Document) {
+  const dynamicElements = root.querySelectorAll<HTMLElement>(
+    "[\\:ax-query], [\\:ax-mutate]",
+  );
+  dynamicElements.forEach((el) => {
+    if (el.hasAttribute(":ax-query")) {
+      const expr = el.getAttribute(":ax-query")!;
+      const val = evaluateExpression(expr, getContext(el));
+      if (val) el.setAttribute("ax-query", String(val));
+      el.removeAttribute(":ax-query");
+    }
+    if (el.hasAttribute(":ax-mutate")) {
+      const expr = el.getAttribute(":ax-mutate")!;
+      const val = evaluateExpression(expr, getContext(el));
+      if (val) el.setAttribute("ax-mutate", String(val));
+      el.removeAttribute(":ax-mutate");
+    }
+  });
+}
+
+export function scanAndInitialize(root: HTMLElement | Document = document) {
+  // 0. Unwrap Dynamic Typescript Clients first
+  evaluateDynamicAttributes(root);
+
+  // 1. Initialize ax-query blocks
+  const queries = root.querySelectorAll("[ax-query]");
+  queries.forEach((el) => {
+    const htmlEl = el as HTMLElement;
+    updateContext(htmlEl, {});
+
+    const triggerMode = htmlEl.getAttribute("ax-trigger") || "load";
+    if (triggerMode === "load") {
+      connectQuery(htmlEl);
+    } else if (triggerMode === "intersect") {
+      intersectionObserver.observe(htmlEl);
+    } else {
+      htmlEl.addEventListener(triggerMode, (e) => {
+        e.preventDefault();
+        connectQuery(htmlEl);
+      });
+    }
+  });
+
+  // 2. Initialize ax-mutate blocks
+  const mutates = root.querySelectorAll("[ax-mutate]");
+  mutates.forEach((el) => {
+    const htmlEl = el as HTMLElement;
+    updateContext(htmlEl, {});
+
+    const trigger = htmlEl.tagName === "FORM" ? "submit" : "click";
+
+    htmlEl.addEventListener(trigger, (e) => {
+      if (
+        htmlEl.tagName === "A" ||
+        htmlEl.tagName === "BUTTON" ||
+        htmlEl.tagName === "FORM"
+      ) {
+        e.preventDefault();
+      }
+      executeMutation(htmlEl);
+    });
+  });
+
+  // 3. Action Modifiers (e.g., ax-trigger="refresh")
+  const refreshers = root.querySelectorAll('[ax-trigger="refresh"]');
+  refreshers.forEach((el) => {
+    const htmlEl = el as HTMLElement;
+    htmlEl.addEventListener("click", (e) => {
+      e.preventDefault();
+
+      const parentQuery = htmlEl.closest("[ax-query]") as HTMLElement;
+      if (parentQuery) {
+        const attrVal = parentQuery.getAttribute("ax-query")!;
+        const parsed = parseRpcCall(parentQuery, attrVal);
+
+        if (parsed) {
+          const route = resolveRoute(parsed.target);
+          if (route) {
+            const queryKey = `${route.namespace}:${route.id}:${JSON.stringify(parsed.args)}`;
+            const activeQuery = queryRegistry.get(queryKey);
+            if (activeQuery) {
+              activeQuery.fetch(true);
+            } else {
+              connectQuery(parentQuery);
+            }
+          }
+        }
+      }
+    });
+  });
+}
+
+export function initMutationObserver() {
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      mutation.addedNodes.forEach((node) => {
+        if (node instanceof HTMLElement) {
+          scanAndInitialize(node);
+        }
+      });
+    });
+  });
+
+  observer.observe(document.body, { childList: true, subtree: true });
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+// FILE: src/index.ts
+import { initWasm, setAuthToken, clearAuthToken } from "./core/wasm";
+import { scanAndInitialize, initMutationObserver } from "./dom/scanner";
+import { connectQuery } from "./dom/lifecycle";
+import { AtmxConfig, InitResult } from "./core/types";
+import "./dom/components/engine-status";
+
+export const ATMX_VERSION = "0.42.0";
+
+class ATMX {
+  public version = ATMX_VERSION;
+  public initialized = false;
+  public debug = false;
+
+  public async init(config: AtmxConfig): Promise<InitResult> {
+    if (this.initialized) {
+      return { ok: true, contracts: {}, initDurationMs: 0 };
+    }
+
+    const result = await initWasm(config);
+
+    if (result.ok) {
+      this.debug = config.debug || false;
+
+      initMutationObserver();
+      scanAndInitialize(document.body);
+
+      this.initialized = true;
+      if (this.debug)
+        console.log(
+          "%c🚀 ATMX Debug Mode: Enabled",
+          "color: #2563eb; font-weight: bold;",
+        );
+      console.log(
+        `✅ ATMX v${this.version} Online (${result.initDurationMs}ms). Reactive Engine Started.`,
+      );
+
+      document.dispatchEvent(new CustomEvent("atmx:ready", { detail: result }));
+    } else {
+      console.error("❌ ATMX Initialization Failed:", result.error);
+      // Broadcast fatal error so UI components can catch it
+      document.dispatchEvent(
+        new CustomEvent("atmx:error", { detail: result.error }),
+      );
+    }
+
+    return result;
+  }
+
+  public triggerQuery(elementOrSelector: string | HTMLElement) {
+    const el =
+      typeof elementOrSelector === "string"
+        ? (document.querySelector(elementOrSelector) as HTMLElement)
+        : elementOrSelector;
+
+    if (el && el instanceof HTMLElement && el.hasAttribute("ax-query")) {
+      connectQuery(el);
+    }
+  }
+
+  public on(
+    eventName: "ready" | "data" | "error" | "success" | "contract-loaded",
+    callback: (e: any) => void,
+  ) {
+    document.addEventListener(`atmx:${eventName}`, callback);
+  }
+
+  public setAuthToken(namespace: string, methodName: string, token: string) {
+    setAuthToken(namespace, methodName, token);
+  }
+
+  public clearAuthToken(namespace: string, methodName: string) {
+    clearAuthToken(namespace, methodName);
+  }
+}
+
+export const atmx = new ATMX();
+if (typeof window !== "undefined") (window as any).atmx = atmx;

package/src/resolver/evaluator.ts

@@ -0,0 +1,46 @@
+// FILE: src/resolver/evaluator.ts
+import { AtmxContextData } from "../core/context";
+
+/**
+ * Safely evaluates a JS expression from an HTML attribute against the local ATMX Context.
+ */
+export function evaluateExpression(
+  expr: string,
+  context: AtmxContextData,
+  locals: Record<string, any> = {},
+): any {
+  if (!expr) return undefined;
+  try {
+    const keys = Object.keys(locals);
+    const values = Object.values(locals);
+
+    // Dynamically build a function that accepts $data, $error, $state, AND our locals ($item, etc.)
+    const fn = new Function(
+      "$data",
+      "$error",
+      "$state",
+      ...keys,
+      `return (${expr});`,
+    );
+    return fn(context.data || {}, context.error || {}, context, ...values);
+  } catch (e) {
+    console.error(`ATMX Eval Error: ${expr}`, e);
+    return undefined;
+  }
+}
+
+export function executeAction(
+  expr: string,
+  context: AtmxContextData,
+  locals: Record<string, any> = {},
+): void {
+  if (!expr) return;
+  try {
+    const keys = Object.keys(locals);
+    const values = Object.values(locals);
+    const fn = new Function("$data", "$error", "$state", ...keys, expr);
+    fn(context.data || {}, context.error || {}, context, ...values);
+  } catch (e) {
+    console.error(`ATMX Action Error: ${expr}`, e);
+  }
+}

package/src/resolver/render.ts

@@ -0,0 +1,196 @@
+// FILE: src/resolver/render.ts
+import { AtmxContextData } from "../core/context";
+import { evaluateExpression } from "./evaluator";
+
+export function renderContext(rootEl: HTMLElement, context: AtmxContextData) {
+  walkAndRender(rootEl, context, true, {});
+}
+
+function walkAndRender(
+  node: HTMLElement,
+  context: AtmxContextData,
+  isRoot: boolean,
+  locals: Record<string, any>,
+) {
+  // Stop traversal if we hit an independent reactive boundary
+  if (
+    !isRoot &&
+    (node.hasAttribute("ax-query") || node.hasAttribute("ax-mutate"))
+  ) {
+    return;
+  }
+
+  // ✨ PHASE 1: DECLARATIVE LIST RENDERING (ax-for)
+  if (node.hasAttribute("ax-for")) {
+    handleAxFor(node, context, locals);
+    return; // Stop normal traversal for the template node!
+  }
+
+  // 1. STATE RENDERING (ax-when)
+  if (node.hasAttribute("ax-when")) {
+    const expectedStates = node
+      .getAttribute("ax-when")!
+      .split(",")
+      .map((s) => s.trim());
+    if (!expectedStates.includes(context.state)) {
+      node.setAttribute("hidden", "true");
+      node.style.setProperty("display", "none", "important");
+    } else {
+      node.removeAttribute("hidden");
+      node.style.removeProperty("display");
+    }
+  }
+
+  // 2. CONDITIONAL RENDERING (ax-if)
+  if (node.hasAttribute("ax-if")) {
+    const result = evaluateExpression(
+      node.getAttribute("ax-if")!,
+      context,
+      locals,
+    );
+    if (!result) {
+      node.setAttribute("hidden", "");
+      node.style.setProperty("display", "none", "important");
+    } else {
+      node.removeAttribute("hidden");
+      node.style.removeProperty("display");
+    }
+  }
+
+  // 3. TEXT INTERPOLATION (ax-text)
+  if (node.hasAttribute("ax-text")) {
+    const result = evaluateExpression(
+      node.getAttribute("ax-text")!,
+      context,
+      locals,
+    );
+    // ✨ SECURE: textContent completely eliminates XSS vulnerabilities!
+    node.textContent =
+      result !== undefined && result !== null ? String(result) : "";
+  }
+
+  // 4. FIELD-LEVEL ERRORS (ax-error-for)
+  if (node.hasAttribute("ax-error-for")) {
+    const fieldName = node.getAttribute("ax-error-for")!;
+    let errorMessage = "";
+    if (
+      context.state === "error" &&
+      context.error?.code === "ValidationError"
+    ) {
+      const details = context.error.details || "";
+      const lines = details.split("\n");
+      for (const line of lines) {
+        if (line.startsWith(fieldName + ":")) {
+          errorMessage = line.substring(fieldName.length + 1).trim();
+          break;
+        }
+      }
+    }
+    if (errorMessage) {
+      node.textContent = errorMessage;
+      node.removeAttribute("hidden");
+      node.style.removeProperty("display");
+    } else {
+      node.setAttribute("hidden", "");
+      node.style.setProperty("display", "none", "important");
+    }
+  }
+
+  // 5. ATTRIBUTE BINDING (ax-bind:*)
+  Array.from(node.attributes).forEach((attr) => {
+    if (attr.name.startsWith("ax-bind:")) {
+      const targetAttr = attr.name.substring(8);
+      const result = evaluateExpression(attr.value, context, locals);
+      if (result === false || result === null || result === undefined) {
+        node.removeAttribute(targetAttr);
+      } else {
+        node.setAttribute(
+          targetAttr,
+          result === true ? targetAttr : String(result),
+        );
+      }
+    }
+  });
+
+  Array.from(node.children).forEach((child) => {
+    walkAndRender(child as HTMLElement, context, false, locals);
+  });
+}
+
+function handleAxFor(
+  templateNode: HTMLElement,
+  context: AtmxContextData,
+  locals: Record<string, any>,
+) {
+  templateNode.style.display = "none"; // Hide the template node
+
+  if (!templateNode.hasAttribute("data-ax-for-id")) {
+    templateNode.setAttribute(
+      "data-ax-for-id",
+      Math.random().toString(36).substr(2, 9),
+    );
+  }
+  const forId = templateNode.getAttribute("data-ax-for-id")!;
+  const forExpr = templateNode.getAttribute("ax-for")!;
+
+  // Parse: "$item in $data" or "($item, $index) in $data"
+  const match = forExpr.match(
+    /^\s*(?:(?:\(\s*([\w\$]+)\s*,\s*([\w\$]+)\s*\))|([\w\$]+))\s+in\s+(.+)$/,
+  );
+  if (!match) return;
+
+  const itemVar = match[1] || match[3];
+  const indexVar = match[2];
+  const iterableExpr = match[4];
+
+  const iterable = evaluateExpression(iterableExpr, context, locals);
+  const parent = templateNode.parentElement;
+  if (!parent) return;
+
+  const existingClones = Array.from(
+    parent.querySelectorAll(`[data-ax-clone-of="${forId}"]`),
+  ) as HTMLElement[];
+
+  if (!iterable || !Array.isArray(iterable)) {
+    existingClones.forEach((el) => el.remove());
+    return;
+  }
+
+  const keyAttr = templateNode.getAttribute("ax-key");
+  const newClones: HTMLElement[] = [];
+
+  iterable.forEach((item, index) => {
+    const childLocals = { ...locals, [itemVar]: item };
+    if (indexVar) childLocals[indexVar] = index;
+
+    let keyValue = String(index);
+    if (keyAttr) {
+      keyValue = String(evaluateExpression(keyAttr, context, childLocals));
+    }
+
+    // Try to reuse an existing DOM node for performance
+    let clone = existingClones.find(
+      (el) => el.getAttribute("data-ax-key") === keyValue,
+    );
+    if (!clone) {
+      clone = templateNode.cloneNode(true) as HTMLElement;
+      clone.removeAttribute("ax-for");
+      clone.style.removeProperty("display");
+      if (clone.style.length === 0) clone.removeAttribute("style");
+      clone.setAttribute("data-ax-clone-of", forId);
+      clone.setAttribute("data-ax-key", keyValue);
+    }
+
+    // Maintain exact order in the DOM
+    parent.insertBefore(clone, templateNode);
+
+    // Render the contents of the clone with the injected locals!
+    walkAndRender(clone, context, false, childLocals);
+    newClones.push(clone);
+  });
+
+  // Cleanup old clones that are no longer in the list
+  existingClones.forEach((el) => {
+    if (!newClones.includes(el)) el.remove();
+  });
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "useDefineForClassFields": true,
+        "module": "ESNext",
+        "lib": [
+            "ES2020",
+            "DOM",
+            "DOM.Iterable"
+        ],
+        "skipLibCheck": true,
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "noEmit": true,
+        "strict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "include": [
+        "src"
+    ]
+}

package/vite-env.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+
+declare module "*?raw" {
+    const content: string;
+    export default content;
+}
+
+declare module "*?url" {
+    const url: string;
+    export default url;
+}

package/vite.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+export default defineConfig({
+    server: {
+        open: '/example/index.html',
+        proxy: {
+            // Any request to /api will be proxied to your backend
+            '/api': {
+                target: 'http://localhost:8000',
+                changeOrigin: true,
+                rewrite: (path) => path.replace(/^\/api/, '') // Strips /api before sending to backend
+            }
+        }
+    },
+    build: {
+        lib: {
+            entry: resolve(__dirname, 'src/index.ts'),
+            name: 'atmx',
+            fileName: (format) => `atmx.${format}.js`,
+            formats: ['es', 'umd']
+        },
+        assetsInlineLimit: 0,
+        outDir: 'dist',
+        emptyOutDir: true
+    }
+});