zero-query 0.5.2 → 0.7.5

package/index.js

@@ -15,12 +15,15 @@ import { component, mount, mountAll, getInstance, destroy, getRegistry, style }
 import { createRouter, getRouter } from './src/router.js';
 import { createStore, getStore } from './src/store.js';
 import { http } from './src/http.js';
+import { morph } from './src/diff.js';
+import { safeEval } from './src/expression.js';
 import {
   debounce, throttle, pipe, once, sleep,
   escapeHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,
   storage, session, bus,
 } from './src/utils.js';
+import { ZQueryError, ErrorCode, onError, reportError } from './src/errors.js';
 
 
 // ---------------------------------------------------------------------------
@@ -28,16 +31,16 @@ import {
 // ---------------------------------------------------------------------------
 
 /**
- * Main selector function
+ * Main selector function — always returns a ZQueryCollection (like jQuery).
  * 
- *   $('selector')         → single Element (querySelector)
- *   $('<div>hello</div>') → create element (first created node)
- *   $(element)            → return element as-is
+ *   $('selector')         → ZQueryCollection (querySelectorAll)
+ *   $('<div>hello</div>') → ZQueryCollection from created elements
+ *   $(element)            → ZQueryCollection wrapping the element
  *   $(fn)                 → DOMContentLoaded shorthand
  * 
  * @param {string|Element|NodeList|Function} selector
  * @param {string|Element} [context]
- * @returns {Element|null}
+ * @returns {ZQueryCollection}
  */
 function $(selector, context) {
   // $(fn) → DOM ready shorthand
@@ -57,8 +60,6 @@ $.tag      = query.tag;
 Object.defineProperty($, 'name', {
   value: query.name, writable: true, configurable: true
 });
-$.attr     = query.attr;
-$.data     = query.data;
 $.children = query.children;
 
 // --- Collection selector ---------------------------------------------------
@@ -100,6 +101,8 @@ $.getInstance = getInstance;
 $.destroy     = destroy;
 $.components  = getRegistry;
 $.style       = style;
+$.morph       = morph;
+$.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
 $.router    = createRouter;
@@ -138,6 +141,11 @@ $.storage    = storage;
 $.session    = session;
 $.bus        = bus;
 
+// --- Error handling --------------------------------------------------------
+$.onError     = onError;
+$.ZQueryError = ZQueryError;
+$.ErrorCode   = ErrorCode;
+
 // --- Meta ------------------------------------------------------------------
 $.version = '__VERSION__';
 $.meta    = {};                // populated at build time by CLI bundler
@@ -169,9 +177,12 @@ export {
   queryAll,
   reactive, Signal, signal, computed, effect,
   component, mount, mountAll, getInstance, destroy, getRegistry, style,
+  morph,
+  safeEval,
   createRouter, getRouter,
   createStore, getStore,
   http,
+  ZQueryError, ErrorCode, onError, reportError,
   debounce, throttle, pipe, once, sleep,
   escapeHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "0.5.2",
+  "version": "0.7.5",
   "description": "Lightweight modern frontend library — jQuery-like selectors, reactive components, SPA router, and state management with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,8 +9,10 @@
   },
   "files": [
     "src",
+    "tests",
     "dist",
     "cli",
+    "types",
     "index.js",
     "index.d.ts",
     "LICENSE",
@@ -21,7 +23,9 @@
     "dev": "node cli/index.js dev zquery-website",
     "dev-lib": "node cli/index.js build --watch",
     "bundle": "node cli/index.js bundle",
-    "bundle:app": "node cli/index.js bundle zquery-website --minimal"
+    "bundle:app": "node cli/index.js bundle zquery-website --minimal",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "dom",
@@ -50,7 +54,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
+  "devDependencies": {
+    "jsdom": "^28.1.0",
+    "vitest": "^4.0.18",
     "zero-http": "^0.2.3"
   }
 }

package/src/component.js

@@ -20,6 +20,9 @@
  */
 
 import { reactive } from './reactive.js';
+import { morph } from './diff.js';
+import { safeEval } from './expression.js';
+import { reportError, ErrorCode, ZQueryError } from './errors.js';
 
 // ---------------------------------------------------------------------------
 // Component registry & external resource cache
@@ -195,10 +198,27 @@ class Component {
     this._destroyed = false;
     this._updateQueued = false;
     this._listeners = [];
+    this._watchCleanups = [];
 
     // Refs map
     this.refs = {};
 
+    // Capture slot content before first render replaces it
+    this._slotContent = {};
+    const defaultSlotNodes = [];
+    [...el.childNodes].forEach(node => {
+      if (node.nodeType === 1 && node.hasAttribute('slot')) {
+        const slotName = node.getAttribute('slot');
+        if (!this._slotContent[slotName]) this._slotContent[slotName] = '';
+        this._slotContent[slotName] += node.outerHTML;
+      } else if (node.nodeType === 1 || (node.nodeType === 3 && node.textContent.trim())) {
+        defaultSlotNodes.push(node.nodeType === 1 ? node.outerHTML : node.textContent);
+      }
+    });
+    if (defaultSlotNodes.length) {
+      this._slotContent['default'] = defaultSlotNodes.join('');
+    }
+
     // Props (read-only from parent)
     this.props = Object.freeze({ ...props });
 
@@ -207,10 +227,25 @@ class Component {
       ? definition.state()
       : { ...(definition.state || {}) };
 
-    this.state = reactive(initialState, () => {
-      if (!this._destroyed) this._scheduleUpdate();
+    this.state = reactive(initialState, (key, value, old) => {
+      if (!this._destroyed) {
+        // Run watchers for the changed key
+        this._runWatchers(key, value, old);
+        this._scheduleUpdate();
+      }
     });
 
+    // Computed properties — lazy getters derived from state
+    this.computed = {};
+    if (definition.computed) {
+      for (const [name, fn] of Object.entries(definition.computed)) {
+        Object.defineProperty(this.computed, name, {
+          get: () => fn.call(this, this.state.__raw || this.state),
+          enumerable: true
+        });
+      }
+    }
+
     // Bind all user methods to this instance
     for (const [key, val] of Object.entries(definition)) {
       if (typeof val === 'function' && !_reservedKeys.has(key)) {
@@ -219,7 +254,36 @@ class Component {
     }
 
     // Init lifecycle
-    if (definition.init) definition.init.call(this);
+    if (definition.init) {
+      try { definition.init.call(this); }
+      catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${definition._name}" init() threw`, { component: definition._name }, err); }
+    }
+
+    // Set up watchers after init so initial state is ready
+    if (definition.watch) {
+      this._prevWatchValues = {};
+      for (const key of Object.keys(definition.watch)) {
+        this._prevWatchValues[key] = _getPath(this.state.__raw || this.state, key);
+      }
+    }
+  }
+
+  // Run registered watchers for a changed key
+  _runWatchers(changedKey, value, old) {
+    const watchers = this._def.watch;
+    if (!watchers) return;
+    for (const [key, handler] of Object.entries(watchers)) {
+      // Match exact key or parent key (e.g. watcher on 'user' fires when 'user.name' changes)
+      if (changedKey === key || key.startsWith(changedKey + '.') || changedKey.startsWith(key + '.') || changedKey === key) {
+        const currentVal = _getPath(this.state.__raw || this.state, key);
+        const prevVal = this._prevWatchValues?.[key];
+        if (currentVal !== prevVal) {
+          const fn = typeof handler === 'function' ? handler : handler.handler;
+          if (typeof fn === 'function') fn.call(this, currentVal, prevVal);
+          if (this._prevWatchValues) this._prevWatchValues[key] = currentVal;
+        }
+      }
+    }
   }
 
   // Schedule a batched DOM update (microtask)
@@ -317,11 +381,14 @@ class Component {
     if (def.styleUrl && !def._styleLoaded) {
       const su = def.styleUrl;
       if (typeof su === 'string') {
-        def._externalStyles = await _fetchResource(_resolveUrl(su, base));
+        const resolved = _resolveUrl(su, base);
+        def._externalStyles = await _fetchResource(resolved);
+        def._resolvedStyleUrls = [resolved];
       } else if (Array.isArray(su)) {
         const urls = su.map(u => _resolveUrl(u, base));
         const results = await Promise.all(urls.map(u => _fetchResource(u)));
         def._externalStyles = results.join('\n');
+        def._resolvedStyleUrls = urls;
       }
       def._styleLoaded = true;
     }
@@ -394,17 +461,29 @@ class Component {
       // Then do global {{expression}} interpolation on the remaining content
       html = html.replace(/\{\{(.+?)\}\}/g, (_, expr) => {
         try {
-          return new Function('state', 'props', '$', `with(state){return ${expr.trim()}}`)(
+          const result = safeEval(expr.trim(), [
             this.state.__raw || this.state,
-            this.props,
-            typeof window !== 'undefined' ? window.$ : undefined
-          );
+            { props: this.props, computed: this.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+          ]);
+          return result != null ? result : '';
         } catch { return ''; }
       });
     } else {
       html = '';
     }
 
+    // -- Slot distribution ----------------------------------------
+    // Replace <slot> elements with captured slot content from parent.
+    // <slot> → default slot content
+    // <slot name="header"> → named slot content
+    // Fallback content between <slot>...</slot> used when no content provided.
+    if (html.includes('<slot')) {
+      html = html.replace(/<slot(?:\s+name="([^"]*)")?\s*(?:\/>|>([\s\S]*?)<\/slot>)/g, (_, name, fallback) => {
+        const slotName = name || 'default';
+        return this._slotContent[slotName] || fallback || '';
+      });
+    }
+
     // Combine inline styles + external styles
     const combinedStyles = [
       this._def.styles || '',
@@ -415,33 +494,52 @@ class Component {
     if (!this._mounted && combinedStyles) {
       const scopeAttr = `z-s${this._uid}`;
       this._el.setAttribute(scopeAttr, '');
-      const scoped = combinedStyles.replace(/([^{}]+)\{/g, (match, selector) => {
+      let inAtBlock = 0;
+      const scoped = combinedStyles.replace(/([^{}]+)\{|\}/g, (match, selector) => {
+        if (match === '}') {
+          if (inAtBlock > 0) inAtBlock--;
+          return match;
+        }
+        const trimmed = selector.trim();
+        // Don't scope @-rules (@media, @keyframes, @supports, @container, @layer, @font-face, etc.)
+        if (trimmed.startsWith('@')) {
+          inAtBlock++;
+          return match;
+        }
+        // Don't scope keyframe stops (from, to, 0%, 50%, etc.)
+        if (inAtBlock > 0 && /^[\d%\s,fromto]+$/.test(trimmed.replace(/\s/g, ''))) {
+          return match;
+        }
         return selector.split(',').map(s => `[${scopeAttr}] ${s.trim()}`).join(', ') + ' {';
       });
       const styleEl = document.createElement('style');
       styleEl.textContent = scoped;
       styleEl.setAttribute('data-zq-component', this._def._name || '');
+      styleEl.setAttribute('data-zq-scope', scopeAttr);
+      if (this._def._resolvedStyleUrls) {
+        styleEl.setAttribute('data-zq-style-urls', this._def._resolvedStyleUrls.join(' '));
+        if (this._def.styles) {
+          styleEl.setAttribute('data-zq-inline', this._def.styles);
+        }
+      }
       document.head.appendChild(styleEl);
       this._styleEl = styleEl;
     }
 
     // -- Focus preservation ----------------------------------------
-    // Before replacing innerHTML, save focus state so we can restore
-    // cursor position after the DOM is rebuilt.  Works for any focused
-    // input/textarea/select inside the component, not only z-model.
+    // DOM morphing preserves unchanged nodes naturally, but we still
+    // track focus for cases where the focused element's subtree changes.
     let _focusInfo = null;
     const _active = document.activeElement;
     if (_active && this._el.contains(_active)) {
       const modelKey = _active.getAttribute?.('z-model');
       const refKey = _active.getAttribute?.('z-ref');
-      // Build a selector that can locate the same element after re-render
       let selector = null;
       if (modelKey) {
         selector = `[z-model="${modelKey}"]`;
       } else if (refKey) {
         selector = `[z-ref="${refKey}"]`;
       } else {
-        // Fallback: match by tag + type + name + placeholder combination
         const tag = _active.tagName.toLowerCase();
         if (tag === 'input' || tag === 'textarea' || tag === 'select') {
           let s = tag;
@@ -461,8 +559,13 @@ class Component {
       }
     }
 
-    // Update DOM
-    this._el.innerHTML = html;
+    // Update DOM via morphing (diffing) — preserves unchanged nodes
+    // First render uses innerHTML for speed; subsequent renders morph.
+    if (!this._mounted) {
+      this._el.innerHTML = html;
+    } else {
+      morph(this._el, html);
+    }
 
     // Process structural & attribute directives
     this._processDirectives();
@@ -472,10 +575,10 @@ class Component {
     this._bindRefs();
     this._bindModels();
 
-    // Restore focus after re-render
+    // Restore focus if the morph replaced the focused element
     if (_focusInfo) {
       const el = this._el.querySelector(_focusInfo.selector);
-      if (el) {
+      if (el && el !== document.activeElement) {
         el.focus();
         try {
           if (_focusInfo.start !== null && _focusInfo.start !== undefined) {
@@ -490,9 +593,15 @@ class Component {
 
     if (!this._mounted) {
       this._mounted = true;
-      if (this._def.mounted) this._def.mounted.call(this);
+      if (this._def.mounted) {
+        try { this._def.mounted.call(this); }
+        catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${this._def._name}" mounted() threw`, { component: this._def._name }, err); }
+      }
     } else {
-      if (this._def.updated) this._def.updated.call(this);
+      if (this._def.updated) {
+        try { this._def.updated.call(this); }
+        catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${this._def._name}" updated() threw`, { component: this._def._name }, err); }
+      }
     }
   }
 
@@ -701,18 +810,13 @@ class Component {
   }
 
   // ---------------------------------------------------------------------------
-  // Expression evaluator — runs expr in component context (state, props, refs)
+  // Expression evaluator — CSP-safe parser (no eval / new Function)
   // ---------------------------------------------------------------------------
   _evalExpr(expr) {
-    try {
-      return new Function('state', 'props', 'refs', '$',
-        `with(state){return (${expr})}`)(
-        this.state.__raw || this.state,
-        this.props,
-        this.refs,
-        typeof window !== 'undefined' ? window.$ : undefined
-      );
-    } catch { return undefined; }
+    return safeEval(expr, [
+      this.state.__raw || this.state,
+      { props: this.props, refs: this.refs, computed: this.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+    ]);
   }
 
   // ---------------------------------------------------------------------------
@@ -774,13 +878,15 @@ class Component {
         const evalReplace = (str, item, index) =>
           str.replace(/\{\{(.+?)\}\}/g, (_, inner) => {
             try {
-              return new Function(itemVar, indexVar, 'state', 'props', '$',
-                `with(state){return (${inner.trim()})}`)(
-                item, index,
+              const loopScope = {};
+              loopScope[itemVar] = item;
+              loopScope[indexVar] = index;
+              const result = safeEval(inner.trim(), [
+                loopScope,
                 this.state.__raw || this.state,
-                this.props,
-                typeof window !== 'undefined' ? window.$ : undefined
-              );
+                { props: this.props, computed: this.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+              ]);
+              return result != null ? result : '';
             } catch { return ''; }
           });
 
@@ -945,7 +1051,10 @@ class Component {
   destroy() {
     if (this._destroyed) return;
     this._destroyed = true;
-    if (this._def.destroyed) this._def.destroyed.call(this);
+    if (this._def.destroyed) {
+      try { this._def.destroyed.call(this); }
+      catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${this._def._name}" destroyed() threw`, { component: this._def._name }, err); }
+    }
     this._listeners.forEach(({ event, handler }) => this._el.removeEventListener(event, handler));
     this._listeners = [];
     if (this._styleEl) this._styleEl.remove();
@@ -958,7 +1067,8 @@ class Component {
 // Reserved definition keys (not user methods)
 const _reservedKeys = new Set([
   'state', 'render', 'styles', 'init', 'mounted', 'updated', 'destroyed', 'props',
-  'templateUrl', 'styleUrl', 'templates', 'pages', 'activePage', 'base'
+  'templateUrl', 'styleUrl', 'templates', 'pages', 'activePage', 'base',
+  'computed', 'watch'
 ]);
 
 
@@ -972,8 +1082,11 @@ const _reservedKeys = new Set([
  * @param {object} definition — component definition
  */
 export function component(name, definition) {
+  if (!name || typeof name !== 'string') {
+    throw new ZQueryError(ErrorCode.COMP_INVALID_NAME, 'Component name must be a non-empty string');
+  }
   if (!name.includes('-')) {
-    throw new Error(`zQuery: Component name "${name}" must contain a hyphen (Web Component convention)`);
+    throw new ZQueryError(ErrorCode.COMP_INVALID_NAME, `Component name "${name}" must contain a hyphen (Web Component convention)`);
   }
   definition._name = name;
 
@@ -998,10 +1111,10 @@ export function component(name, definition) {
  */
 export function mount(target, componentName, props = {}) {
   const el = typeof target === 'string' ? document.querySelector(target) : target;
-  if (!el) throw new Error(`zQuery: Mount target "${target}" not found`);
+  if (!el) throw new ZQueryError(ErrorCode.COMP_MOUNT_TARGET, `Mount target "${target}" not found`, { target });
 
   const def = _registry.get(componentName);
-  if (!def) throw new Error(`zQuery: Component "${componentName}" not registered`);
+  if (!def) throw new ZQueryError(ErrorCode.COMP_NOT_FOUND, `Component "${componentName}" not registered`, { component: componentName });
 
   // Destroy existing instance
   if (_instances.has(el)) _instances.get(el).destroy();
@@ -1024,12 +1137,40 @@ export function mountAll(root = document.body) {
 
       // Extract props from attributes
       const props = {};
+
+      // Find parent component instance for evaluating dynamic prop expressions
+      let parentInstance = null;
+      let ancestor = tag.parentElement;
+      while (ancestor) {
+        if (_instances.has(ancestor)) {
+          parentInstance = _instances.get(ancestor);
+          break;
+        }
+        ancestor = ancestor.parentElement;
+      }
+
       [...tag.attributes].forEach(attr => {
-        if (!attr.name.startsWith('@') && !attr.name.startsWith('z-')) {
-          // Try JSON parse for objects/arrays
-          try { props[attr.name] = JSON.parse(attr.value); }
-          catch { props[attr.name] = attr.value; }
+        if (attr.name.startsWith('@') || attr.name.startsWith('z-')) return;
+
+        // Dynamic prop: :propName="expression" — evaluate in parent context
+        if (attr.name.startsWith(':')) {
+          const propName = attr.name.slice(1);
+          if (parentInstance) {
+            props[propName] = safeEval(attr.value, [
+              parentInstance.state.__raw || parentInstance.state,
+              { props: parentInstance.props, refs: parentInstance.refs, computed: parentInstance.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+            ]);
+          } else {
+            // No parent — try JSON parse
+            try { props[propName] = JSON.parse(attr.value); }
+            catch { props[propName] = attr.value; }
+          }
+          return;
         }
+
+        // Static prop
+        try { props[attr.name] = JSON.parse(attr.value); }
+        catch { props[attr.name] = attr.value; }
       });
 
       const instance = new Component(tag, def, props);