mez-easyjs 0.1.0

package/src/runtime/component.js

@@ -0,0 +1,222 @@
+import { reactive } from './reactive.js';
+import { injectStyles } from './css.js';
+import { queueJob } from './scheduler.js';
+import { EasyError, reportError, peekBoundary } from './errors.js';
+
+/**
+ * defineComponent — used by compiled SFCs and hand-written components.
+ */
+export function defineComponent(options) {
+  if (typeof options === 'function') {
+    return defineComponent({ setup: options });
+  }
+  const comp = { ...options, __isEasyComponent: true };
+  return comp;
+}
+
+/**
+ * Mount a component definition into a host element.
+ */
+export function mountComponent(defn, host, props = {}, appContext = {}) {
+  if (!defn) {
+    const err = new EasyError('Cannot mount undefined component', {
+      hint: 'Check the import path and that the file exports default.',
+      filename: appContext.parent?.filename
+    });
+    reportError(err);
+    const boundary = peekBoundary();
+    if (boundary) boundary.capture(err);
+    throw err;
+  }
+
+  if (typeof defn === 'function' && !defn.__isEasyComponent && !defn.setup) {
+    return Promise.resolve(defn()).then((mod) => {
+      const resolved = mod?.default || mod;
+      return mountComponent(resolved, host, props, appContext);
+    });
+  }
+  if (defn && typeof defn.then === 'function') {
+    return defn.then((mod) => {
+      const resolved = mod?.default || mod;
+      return mountComponent(resolved, host, props, appContext);
+    });
+  }
+
+  const options = defn.__isEasyComponent || defn.setup ? defn : defineComponent(defn);
+  const compName = options.name || options.filename || 'Anonymous';
+
+  if (options.styles && options.scopeId) {
+    injectStyles(options.scopeId, options.styles);
+  }
+
+  const instance = {
+    props: reactive({ ...props }),
+    appContext,
+    parent: appContext.parent || null,
+    filename: options.filename || null,
+    name: compName,
+    isMounted: false,
+    isUnmounted: false,
+    cleanups: [],
+    children: [],
+    emit(event, ...args) {
+      const handler = props[`on${capitalize(event)}`] || props[`on${event}`];
+      if (typeof handler === 'function') handler(...args);
+    }
+  };
+
+  const ctx = {
+    props: instance.props,
+    emit: instance.emit.bind(instance),
+    appContext,
+    expose(api) {
+      Object.assign(instance, api);
+    }
+  };
+
+  let setupResult = {};
+  try {
+    if (typeof options.setup === 'function') {
+      setupResult = options.setup(instance.props, ctx) || {};
+    } else {
+      const data = typeof options.data === 'function' ? options.data.call({}) : (options.data || {});
+      const state = reactive(data);
+      const methods = {};
+      for (const [name, fn] of Object.entries(options.methods || {})) {
+        if (typeof fn === 'function') {
+          methods[name] = fn.bind(createBoundThis(state, methods, instance));
+        }
+      }
+      setupResult = {
+        state,
+        methods,
+        mount(el) {
+          if (options.render) options.render.call(createBoundThis(state, methods, instance), el);
+        }
+      };
+    }
+  } catch (err) {
+    const easy = new EasyError(err.message || String(err), {
+      component: compName,
+      filename: options.filename,
+      cause: err,
+      hint: 'Fix the error in setup()/data() and save to retry via HMR.'
+    });
+    reportError(easy);
+    const boundary = peekBoundary();
+    if (boundary) {
+      boundary.capture(easy);
+      return { $el: host, state: null, unmount() {}, isUnmounted: true };
+    }
+    throw easy;
+  }
+
+  instance.state = setupResult.state;
+  instance.methods = setupResult.methods || {};
+  instance.$el = host;
+
+  const boundThis = createBoundThis(instance.state || {}, instance.methods, instance);
+  for (const key of Object.keys(instance.methods)) {
+    const fn = instance.methods[key];
+    if (typeof fn === 'function') {
+      instance.methods[key] = fn.bind(boundThis);
+    }
+  }
+
+  callHook(options.beforeMount || setupResult.beforeMount, boundThis, compName);
+
+  try {
+    if (typeof setupResult.mount === 'function') {
+      setupResult.mount(host, instance);
+    }
+  } catch (err) {
+    const easy = new EasyError(err.message || String(err), {
+      component: compName,
+      filename: options.filename,
+      cause: err,
+      hint: 'Error while mounting the template. Check directives and child components.'
+    });
+    reportError(easy);
+    const boundary = peekBoundary();
+    if (boundary) {
+      boundary.capture(easy);
+      return {
+        $el: host,
+        state: instance.state,
+        appContext,
+        props: instance.props,
+        unmount() {
+          instance.isUnmounted = true;
+        }
+      };
+    }
+    throw easy;
+  }
+
+  instance.isMounted = true;
+  callHook(options.mounted || setupResult.mounted, boundThis, compName);
+
+  instance.unmount = () => {
+    if (instance.isUnmounted) return;
+    callHook(options.beforeUnmount || setupResult.beforeUnmount, boundThis, compName);
+    for (const child of instance.children) {
+      if (child.unmount) child.unmount();
+    }
+    if (typeof setupResult.unmount === 'function') setupResult.unmount(host, instance);
+    for (const fn of instance.cleanups) fn();
+    host.innerHTML = '';
+    instance.isUnmounted = true;
+    callHook(options.unmounted || setupResult.unmounted, boundThis, compName);
+  };
+
+  return instance;
+}
+
+export function unmountComponent(instance) {
+  if (instance && instance.unmount) instance.unmount();
+}
+
+function callHook(hook, ctx, name) {
+  if (typeof hook === 'function') {
+    try {
+      hook.call(ctx);
+    } catch (e) {
+      reportError(
+        new EasyError(e.message || String(e), {
+          component: name,
+          cause: e,
+          hint: 'Lifecycle hook threw. See stack below.'
+        })
+      );
+    }
+  }
+}
+
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function createBoundThis(state, methods, instance) {
+  return new Proxy(
+    {},
+    {
+      get(_, key) {
+        if (key in methods) return methods[key];
+        if (state && key in state) return state[key];
+        if (key === '$props') return instance.props;
+        if (key === '$emit') return instance.emit.bind(instance);
+        if (key === '$el') return instance.$el;
+        if (key === '$nextTick') return (fn) => queueJob(fn);
+        if (key === '$router') return instance.appContext?.router || null;
+        return undefined;
+      },
+      set(_, key, value) {
+        if (state) {
+          state[key] = value;
+          return true;
+        }
+        return false;
+      }
+    }
+  );
+}

package/src/runtime/css.js

@@ -0,0 +1,35 @@
+const styleMap = new Map();
+
+/**
+ * Inject scoped CSS once per scope id.
+ */
+export function injectStyles(scopeId, cssText) {
+  if (!cssText || typeof document === 'undefined') return;
+  if (styleMap.has(scopeId)) return;
+  const el = document.createElement('style');
+  el.setAttribute('data-easy-scope', scopeId);
+  el.textContent = cssText;
+  document.head.appendChild(el);
+  styleMap.set(scopeId, el);
+}
+
+/**
+ * Replace scoped CSS in-place (HMR) — preserves other app state.
+ */
+export function replaceStyles(scopeId, cssText) {
+  if (!scopeId || typeof document === 'undefined') return;
+  const existing = styleMap.get(scopeId);
+  if (existing) {
+    existing.textContent = cssText || '';
+    return;
+  }
+  if (cssText) injectStyles(scopeId, cssText);
+}
+
+export function removeStyles(scopeId) {
+  const el = styleMap.get(scopeId);
+  if (el) {
+    el.remove();
+    styleMap.delete(scopeId);
+  }
+}

package/src/runtime/errors.js

@@ -0,0 +1,121 @@
+/**
+ * Runtime errors + error boundaries + optional hook for the overlay.
+ */
+
+let overlayHandler = null;
+let boundaryStack = [];
+
+export class EasyError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'EasyError';
+    this.component = options.component || null;
+    this.filename = options.filename || null;
+    this.hint = options.hint || null;
+    this.cause = options.cause || null;
+    this.code = options.code || 'E_RUNTIME';
+  }
+
+  toString() {
+    const loc = [this.component, this.filename].filter(Boolean).join(' · ');
+    const hint = this.hint ? `\nHint: ${this.hint}` : '';
+    return `[easy] ${loc ? loc + '\n' : ''}${this.message}${hint}`;
+  }
+}
+
+export function setOverlayHandler(fn) {
+  overlayHandler = fn;
+}
+
+export function reportError(err, context = {}) {
+  const easy =
+    err instanceof EasyError
+      ? err
+      : new EasyError(err?.message || String(err), {
+          ...context,
+          cause: err
+        });
+
+  console.error(easy.toString());
+  if (easy.cause && easy.cause !== err) console.error(easy.cause);
+  else if (err && err !== easy) console.error(err);
+
+  if (typeof overlayHandler === 'function') {
+    try {
+      overlayHandler(easy, context);
+    } catch (_) {
+      /* ignore overlay failures */
+    }
+  }
+
+  return easy;
+}
+
+export function pushBoundary(boundary) {
+  boundaryStack.push(boundary);
+  return () => {
+    const i = boundaryStack.lastIndexOf(boundary);
+    if (i >= 0) boundaryStack.splice(i, 1);
+  };
+}
+
+export function peekBoundary() {
+  return boundaryStack[boundaryStack.length - 1] || null;
+}
+
+/**
+ * Run fn; on error, notify nearest boundary or overlay.
+ */
+export function withErrorBoundary(fn, context = {}) {
+  try {
+    return fn();
+  } catch (err) {
+    const boundary = peekBoundary();
+    if (boundary && typeof boundary.capture === 'function') {
+      boundary.capture(err, context);
+      return undefined;
+    }
+    reportError(err, context);
+    throw err;
+  }
+}
+
+/**
+ * Create a boundary controller bound to a host element.
+ */
+export function createBoundary(host, options = {}) {
+  const fallback =
+    options.fallback ||
+    'Something went wrong in this section.';
+  let active = true;
+
+  const api = {
+    capture(err, context = {}) {
+      if (!active) return;
+      reportError(err, {
+        component: options.name || 'ErrorBoundary',
+        filename: context.filename,
+        hint: options.hint || 'Check the failing child component. The rest of the app should keep working.',
+        ...context
+      });
+      if (host) {
+        host.innerHTML = '';
+        const box = document.createElement('div');
+        box.setAttribute('data-easy-boundary', '');
+        box.style.cssText =
+          'padding:1rem;border:1px solid rgba(240,160,96,.5);border-radius:8px;background:rgba(240,160,96,.08);color:#f0a060;font:14px/1.45 system-ui,sans-serif';
+        box.textContent = typeof fallback === 'function' ? fallback(err) : String(fallback);
+        host.appendChild(box);
+      }
+      if (typeof options.onError === 'function') options.onError(err);
+    },
+    reset() {
+      if (host) host.innerHTML = '';
+    },
+    dispose() {
+      active = false;
+    }
+  };
+
+  return api;
+}

package/src/runtime/escape.js

@@ -0,0 +1,62 @@
+/**
+ * HTML escaping utilities — XSS protection by default.
+ * Runtime is CSP-safe: no eval, no inline handlers.
+ */
+
+const ESC = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;'
+};
+
+/** Attributes that can navigate / load content — must run through sanitizeUrl. */
+export const URL_ATTRS = new Set([
+  'href',
+  'src',
+  'xlink:href',
+  'formaction',
+  'action',
+  'poster',
+  'cite',
+  'background',
+  'data',
+  'srcdoc'
+]);
+
+export function escapeHtml(value) {
+  if (value == null) return '';
+  return String(value).replace(/[&<>"']/g, (c) => ESC[c]);
+}
+
+export function escapeAttr(value) {
+  if (value == null) return '';
+  return String(value).replace(/[&<"']/g, (c) => ESC[c]);
+}
+
+/**
+ * Block javascript: / vbscript: / data: URLs and common obfuscations
+ * (whitespace, control chars, HTML entities for colon).
+ */
+export function sanitizeUrl(value) {
+  if (value == null) return '';
+  let s = String(value).trim();
+  // Normalize obfuscation often used to bypass naive filters
+  s = s.replace(/[\u0000-\u001F\u007F\s]+/g, '');
+  s = s.replace(/&#0*58;|&#x0*3a;|&colon;/gi, ':');
+  if (/^(javascript|vbscript|data):/i.test(s)) return '';
+  // Reject protocol-relative data-like tricks after decode
+  if (/^data:/i.test(s)) return '';
+  return String(value).trim();
+}
+
+/** True for event handler attribute names (onclick, onload, …). */
+export function isEventAttr(name) {
+  return /^on[a-z]/i.test(String(name || ''));
+}
+
+/** True for attributes that must be URL-sanitized when bound. */
+export function isUrlAttr(name) {
+  return URL_ATTRS.has(String(name || '').toLowerCase());
+}

package/src/runtime/events.js

@@ -0,0 +1,151 @@
+/**
+ * Event delegation at the app root.
+ * Compiled templates set data-e-on="click:methodName" (or multiple).
+ * Never uses inline onclick — CSP-safe.
+ */
+
+import { reportError, EasyError, peekBoundary } from './errors.js';
+
+const ROOTS = new WeakMap();
+
+/**
+ * Live event-handler context. Never snapshot reactive state into a plain
+ * object — `this.count++` / reads must hit the reactive proxy so subscribers
+ * (DOM updaters) run.
+ */
+export function createEventContext(methods, state, extras = {}) {
+  const methodBag = methods || {};
+  const hasKey = (key) =>
+    key === 'methods' ||
+    Object.prototype.hasOwnProperty.call(extras, key) ||
+    Object.prototype.hasOwnProperty.call(methodBag, key) ||
+    (state != null && key in state);
+
+  return new Proxy(
+    {},
+    {
+      get(_, key) {
+        if (key === 'methods') return methodBag;
+        if (Object.prototype.hasOwnProperty.call(extras, key)) return extras[key];
+        if (Object.prototype.hasOwnProperty.call(methodBag, key)) return methodBag[key];
+        if (state != null && key in state) return state[key];
+        return undefined;
+      },
+      set(_, key, value) {
+        if (state != null) {
+          state[key] = value;
+          return true;
+        }
+        extras[key] = value;
+        return true;
+      },
+      has(_, key) {
+        return hasKey(key);
+      },
+      ownKeys() {
+        const keys = new Set([
+          ...Object.keys(methodBag),
+          ...Object.keys(extras),
+          ...(state != null ? Object.keys(state) : [])
+        ]);
+        return [...keys];
+      },
+      getOwnPropertyDescriptor(_, key) {
+        if (hasKey(key)) {
+          return { configurable: true, enumerable: true, writable: true };
+        }
+        return undefined;
+      }
+    }
+  );
+}
+
+export function setupDelegation(root, getContext) {
+  if (!root || ROOTS.has(root)) return;
+
+  const handler = (event) => {
+    let node = event.target;
+    while (node && node !== root) {
+      const attr = node.getAttribute && node.getAttribute('data-e-on');
+      if (attr) {
+        const parts = attr.split(';');
+        for (const part of parts) {
+          const [type, methodRaw, ...argParts] = part.split(':');
+          const method = (methodRaw || '').replace(/\(\s*\)$/, '').trim();
+          if (type === event.type && method) {
+            const ctx = getContext(node);
+            if (ctx) {
+              const fn =
+                ctx[method] ||
+                (ctx.methods && ctx.methods[method]) ||
+                (ctx.__modelHandlers && ctx.__modelHandlers[method]);
+              if (typeof fn === 'function') {
+                try {
+                  const argStr = argParts.join(':');
+                  if (argStr) {
+                    try {
+                      const arg = JSON.parse(argStr);
+                      fn.call(ctx, arg, event);
+                    } catch {
+                      fn.call(ctx, event);
+                    }
+                  } else {
+                    fn.call(ctx, event);
+                  }
+                } catch (err) {
+                  const easy =
+                    err instanceof EasyError
+                      ? err
+                      : new EasyError(err.message || String(err), {
+                          cause: err,
+                          hint: `Error in event handler "${method}".`
+                        });
+                  reportError(easy);
+                  let p = node;
+                  let captured = false;
+                  while (p && p !== root) {
+                    if (p.__easyBoundary) {
+                      p.__easyBoundary.capture(easy);
+                      captured = true;
+                      break;
+                    }
+                    p = p.parentElement;
+                  }
+                  if (!captured) {
+                    const boundary = peekBoundary();
+                    if (boundary) boundary.capture(easy);
+                  }
+                }
+              }
+            }
+            break;
+          }
+        }
+      }
+      node = node.parentNode;
+    }
+  };
+
+  const types = [
+    'click', 'input', 'change', 'submit', 'keydown', 'keyup',
+    'mouseenter', 'mouseleave', 'focus', 'blur'
+  ];
+  for (const type of types) {
+    root.addEventListener(
+      type,
+      handler,
+      type === 'focus' || type === 'blur' || type === 'mouseenter' || type === 'mouseleave'
+    );
+  }
+
+  ROOTS.set(root, handler);
+}
+
+export function on(el, type, fn, options) {
+  el.addEventListener(type, fn, options);
+  return () => el.removeEventListener(type, fn, options);
+}
+
+export function off(el, type, fn, options) {
+  el.removeEventListener(type, fn, options);
+}