zero-query 0.1.0

package/src/reactive.js

@@ -0,0 +1,125 @@
+/**
+ * zQuery Reactive — Proxy-based deep reactivity system
+ * 
+ * Creates observable objects that trigger callbacks on mutation.
+ * Used internally by components and store for auto-updates.
+ */
+
+// ---------------------------------------------------------------------------
+// Deep reactive proxy
+// ---------------------------------------------------------------------------
+export function reactive(target, onChange, _path = '') {
+  if (typeof target !== 'object' || target === null) return target;
+
+  const proxyCache = new WeakMap();
+
+  const handler = {
+    get(obj, key) {
+      if (key === '__isReactive') return true;
+      if (key === '__raw') return obj;
+
+      const value = obj[key];
+      if (typeof value === 'object' && value !== null) {
+        // Return cached proxy or create new one
+        if (proxyCache.has(value)) return proxyCache.get(value);
+        const childProxy = new Proxy(value, handler);
+        proxyCache.set(value, childProxy);
+        return childProxy;
+      }
+      return value;
+    },
+
+    set(obj, key, value) {
+      const old = obj[key];
+      if (old === value) return true;
+      obj[key] = value;
+      onChange(key, value, old);
+      return true;
+    },
+
+    deleteProperty(obj, key) {
+      const old = obj[key];
+      delete obj[key];
+      onChange(key, undefined, old);
+      return true;
+    }
+  };
+
+  return new Proxy(target, handler);
+}
+
+
+// ---------------------------------------------------------------------------
+// Signal — lightweight reactive primitive (inspired by Solid/Preact signals)
+// ---------------------------------------------------------------------------
+export class Signal {
+  constructor(value) {
+    this._value = value;
+    this._subscribers = new Set();
+  }
+
+  get value() {
+    // Track dependency if there's an active effect
+    if (Signal._activeEffect) {
+      this._subscribers.add(Signal._activeEffect);
+    }
+    return this._value;
+  }
+
+  set value(newVal) {
+    if (this._value === newVal) return;
+    this._value = newVal;
+    this._notify();
+  }
+
+  peek() { return this._value; }
+
+  _notify() {
+    this._subscribers.forEach(fn => fn());
+  }
+
+  subscribe(fn) {
+    this._subscribers.add(fn);
+    return () => this._subscribers.delete(fn);
+  }
+
+  toString() { return String(this._value); }
+}
+
+// Active effect tracking
+Signal._activeEffect = null;
+
+/**
+ * Create a signal
+ * @param {*} initial — initial value
+ * @returns {Signal}
+ */
+export function signal(initial) {
+  return new Signal(initial);
+}
+
+/**
+ * Create a computed signal (derived from other signals)
+ * @param {Function} fn — computation function
+ * @returns {Signal}
+ */
+export function computed(fn) {
+  const s = new Signal(undefined);
+  effect(() => { s._value = fn(); s._notify(); });
+  return s;
+}
+
+/**
+ * Create a side-effect that auto-tracks signal dependencies
+ * @param {Function} fn — effect function
+ * @returns {Function} — dispose function
+ */
+export function effect(fn) {
+  const execute = () => {
+    Signal._activeEffect = execute;
+    try { fn(); }
+    finally { Signal._activeEffect = null; }
+  };
+  execute();
+  return () => { /* Signals will hold weak refs if needed */ };
+}

package/src/router.js

@@ -0,0 +1,334 @@
+/**
+ * zQuery Router — Client-side SPA router
+ * 
+ * Supports hash mode (#/path) and history mode (/path).
+ * Route params, query strings, navigation guards, and lazy loading.
+ * 
+ * Usage:
+ *   $.router({
+ *     el: '#app',
+ *     mode: 'hash',
+ *     routes: [
+ *       { path: '/', component: 'home-page' },
+ *       { path: '/user/:id', component: 'user-profile' },
+ *       { path: '/lazy', load: () => import('./pages/lazy.js'), component: 'lazy-page' },
+ *     ],
+ *     fallback: 'not-found'
+ *   });
+ */
+
+import { mount, destroy } from './component.js';
+
+class Router {
+  constructor(config = {}) {
+    this._el = null;
+    this._mode = config.mode || 'history';      // 'history' | 'hash'
+
+    // Base path for sub-path deployments
+    // Priority: explicit config.base → window.__ZQ_BASE → <base href> tag
+    let rawBase = config.base;
+    if (rawBase == null) {
+      rawBase = (typeof window !== 'undefined' && window.__ZQ_BASE) || '';
+      if (!rawBase && typeof document !== 'undefined') {
+        const baseEl = document.querySelector('base');
+        if (baseEl) {
+          try { rawBase = new URL(baseEl.href).pathname; }
+          catch { rawBase = baseEl.getAttribute('href') || ''; }
+          if (rawBase === '/') rawBase = '';    // root = no sub-path
+        }
+      }
+    }
+    // Normalize: ensure leading /, strip trailing /
+    this._base = String(rawBase).replace(/\/+$/, '');
+    if (this._base && !this._base.startsWith('/')) this._base = '/' + this._base;
+
+    this._routes = [];
+    this._fallback = config.fallback || null;
+    this._current = null;                         // { route, params, query, path }
+    this._guards = { before: [], after: [] };
+    this._listeners = new Set();
+    this._instance = null;                        // current mounted component
+
+    // Set outlet element
+    if (config.el) {
+      this._el = typeof config.el === 'string' ? document.querySelector(config.el) : config.el;
+    }
+
+    // Register routes
+    if (config.routes) {
+      config.routes.forEach(r => this.add(r));
+    }
+
+    // Listen for navigation
+    if (this._mode === 'hash') {
+      window.addEventListener('hashchange', () => this._resolve());
+    } else {
+      window.addEventListener('popstate', () => this._resolve());
+    }
+
+    // Intercept link clicks for SPA navigation
+    document.addEventListener('click', (e) => {
+      // Don't intercept modified clicks (Ctrl/Cmd+click = new tab)
+      if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const link = e.target.closest('[z-link]');
+      if (!link) return;
+      if (link.getAttribute('target') === '_blank') return;
+      e.preventDefault();
+      this.navigate(link.getAttribute('z-link'));
+    });
+
+    // Initial resolve
+    if (this._el) {
+      // Defer to allow all components to register
+      queueMicrotask(() => this._resolve());
+    }
+  }
+
+  // --- Route management ----------------------------------------------------
+
+  add(route) {
+    // Compile path pattern into regex
+    const keys = [];
+    const pattern = route.path
+      .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; })
+      .replace(/\*/g, '(.*)');
+    const regex = new RegExp(`^${pattern}$`);
+
+    this._routes.push({ ...route, _regex: regex, _keys: keys });
+
+    // Per-route fallback: register an alias path for the same component.
+    // e.g. { path: '/docs/:section', fallback: '/docs', component: 'docs-page' }
+    // When matched via fallback, missing params are undefined → pages `default` kicks in.
+    if (route.fallback) {
+      const fbKeys = [];
+      const fbPattern = route.fallback
+        .replace(/:(\w+)/g, (_, key) => { fbKeys.push(key); return '([^/]+)'; })
+        .replace(/\*/g, '(.*)');
+      const fbRegex = new RegExp(`^${fbPattern}$`);
+      this._routes.push({ ...route, path: route.fallback, _regex: fbRegex, _keys: fbKeys });
+    }
+
+    return this;
+  }
+
+  remove(path) {
+    this._routes = this._routes.filter(r => r.path !== path);
+    return this;
+  }
+
+  // --- Navigation ----------------------------------------------------------
+
+  navigate(path, options = {}) {
+    let normalized = this._normalizePath(path);
+    if (this._mode === 'hash') {
+      window.location.hash = '#' + normalized;
+    } else {
+      window.history.pushState(options.state || {}, '', this._base + normalized);
+      this._resolve();
+    }
+    return this;
+  }
+
+  replace(path, options = {}) {
+    let normalized = this._normalizePath(path);
+    if (this._mode === 'hash') {
+      window.location.replace('#' + normalized);
+    } else {
+      window.history.replaceState(options.state || {}, '', this._base + normalized);
+      this._resolve();
+    }
+    return this;
+  }
+
+  /**
+   * Normalize an app-relative path and guard against double base-prefixing.
+   * @param {string} path — e.g. '/docs', 'docs', or '/app/docs' when base is '/app'
+   * @returns {string} — always starts with '/'
+   */
+  _normalizePath(path) {
+    let p = path && path.startsWith('/') ? path : (path ? `/${path}` : '/');
+    // Strip base prefix if caller accidentally included it
+    if (this._base) {
+      if (p === this._base) return '/';
+      if (p.startsWith(this._base + '/')) p = p.slice(this._base.length) || '/';
+    }
+    return p;
+  }
+
+  /**
+   * Resolve an app-relative path to a full URL path (including base).
+   * Useful for programmatic link generation.
+   * @param {string} path
+   * @returns {string}
+   */
+  resolve(path) {
+    const normalized = path && path.startsWith('/') ? path : (path ? `/${path}` : '/');
+    return this._base + normalized;
+  }
+
+  back() { window.history.back(); return this; }
+  forward() { window.history.forward(); return this; }
+  go(n) { window.history.go(n); return this; }
+
+  // --- Guards --------------------------------------------------------------
+
+  beforeEach(fn) {
+    this._guards.before.push(fn);
+    return this;
+  }
+
+  afterEach(fn) {
+    this._guards.after.push(fn);
+    return this;
+  }
+
+  // --- Events --------------------------------------------------------------
+
+  onChange(fn) {
+    this._listeners.add(fn);
+    return () => this._listeners.delete(fn);
+  }
+
+  // --- Current state -------------------------------------------------------
+
+  get current() { return this._current; }
+
+  /** The detected or configured base path (read-only) */
+  get base() { return this._base; }
+
+  get path() {
+    if (this._mode === 'hash') {
+      return window.location.hash.slice(1) || '/';
+    }
+    let pathname = window.location.pathname || '/';
+    // Strip trailing slash for consistency (except root '/')
+    if (pathname.length > 1 && pathname.endsWith('/')) {
+      pathname = pathname.slice(0, -1);
+    }
+    if (this._base) {
+      // Exact match: /app
+      if (pathname === this._base) return '/';
+      // Prefix match with boundary: /app/page (but NOT /application)
+      if (pathname.startsWith(this._base + '/')) {
+        return pathname.slice(this._base.length) || '/';
+      }
+    }
+    return pathname;
+  }
+
+  get query() {
+    const search = this._mode === 'hash'
+      ? (window.location.hash.split('?')[1] || '')
+      : window.location.search.slice(1);
+    return Object.fromEntries(new URLSearchParams(search));
+  }
+
+  // --- Internal resolve ----------------------------------------------------
+
+  async _resolve() {
+    const fullPath = this.path;
+    const [pathPart, queryString] = fullPath.split('?');
+    const path = pathPart || '/';
+    const query = Object.fromEntries(new URLSearchParams(queryString || ''));
+
+    // Match route
+    let matched = null;
+    let params = {};
+    for (const route of this._routes) {
+      const m = path.match(route._regex);
+      if (m) {
+        matched = route;
+        route._keys.forEach((key, i) => { params[key] = m[i + 1]; });
+        break;
+      }
+    }
+
+    // Fallback
+    if (!matched && this._fallback) {
+      matched = { component: this._fallback, path: '*', _keys: [], _regex: /.*/ };
+    }
+
+    if (!matched) return;
+
+    const to = { route: matched, params, query, path };
+    const from = this._current;
+
+    // Run before guards
+    for (const guard of this._guards.before) {
+      const result = await guard(to, from);
+      if (result === false) return;                    // Cancel
+      if (typeof result === 'string') {                // Redirect
+        return this.navigate(result);
+      }
+    }
+
+    // Lazy load module if needed
+    if (matched.load) {
+      try { await matched.load(); }
+      catch (err) {
+        console.error(`zQuery Router: Failed to load module for "${matched.path}"`, err);
+        return;
+      }
+    }
+
+    this._current = to;
+
+    // Mount component into outlet
+    if (this._el && matched.component) {
+      // Destroy previous
+      if (this._instance) {
+        this._instance.destroy();
+        this._instance = null;
+      }
+
+      // Create container
+      this._el.innerHTML = '';
+
+      // Pass route params and query as props
+      const props = { ...params, $route: to, $query: query, $params: params };
+
+      // If component is a string (registered name), mount it
+      if (typeof matched.component === 'string') {
+        const container = document.createElement(matched.component);
+        this._el.appendChild(container);
+        this._instance = mount(container, matched.component, props);
+      }
+      // If component is a render function
+      else if (typeof matched.component === 'function') {
+        this._el.innerHTML = matched.component(to);
+      }
+    }
+
+    // Run after guards
+    for (const guard of this._guards.after) {
+      await guard(to, from);
+    }
+
+    // Notify listeners
+    this._listeners.forEach(fn => fn(to, from));
+  }
+
+  // --- Destroy -------------------------------------------------------------
+
+  destroy() {
+    if (this._instance) this._instance.destroy();
+    this._listeners.clear();
+    this._routes = [];
+    this._guards = { before: [], after: [] };
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+let _activeRouter = null;
+
+export function createRouter(config) {
+  _activeRouter = new Router(config);
+  return _activeRouter;
+}
+
+export function getRouter() {
+  return _activeRouter;
+}

package/src/store.js

@@ -0,0 +1,169 @@
+/**
+ * zQuery Store — Global reactive state management
+ * 
+ * A lightweight Redux/Vuex-inspired store with:
+ *   - Reactive state via Proxy
+ *   - Named actions for mutations
+ *   - Key-specific subscriptions
+ *   - Computed getters
+ *   - Middleware support
+ *   - DevTools-friendly (logs actions in dev mode)
+ * 
+ * Usage:
+ *   const store = $.store({
+ *     state: { count: 0, user: null },
+ *     actions: {
+ *       increment(state) { state.count++; },
+ *       setUser(state, user) { state.user = user; }
+ *     },
+ *     getters: {
+ *       doubleCount: (state) => state.count * 2
+ *     }
+ *   });
+ * 
+ *   store.dispatch('increment');
+ *   store.subscribe('count', (val, old) => console.log(val));
+ */
+
+import { reactive } from './reactive.js';
+
+class Store {
+  constructor(config = {}) {
+    this._subscribers = new Map();   // key → Set<fn>
+    this._wildcards = new Set();     // subscribe to all changes
+    this._actions = config.actions || {};
+    this._getters = config.getters || {};
+    this._middleware = [];
+    this._history = [];              // action log
+    this._debug = config.debug || false;
+
+    // Create reactive state
+    const initial = typeof config.state === 'function' ? config.state() : { ...(config.state || {}) };
+
+    this.state = reactive(initial, (key, value, old) => {
+      // Notify key-specific subscribers
+      const subs = this._subscribers.get(key);
+      if (subs) subs.forEach(fn => fn(value, old, key));
+      // Notify wildcard subscribers
+      this._wildcards.forEach(fn => fn(key, value, old));
+    });
+
+    // Build getters as computed properties
+    this.getters = {};
+    for (const [name, fn] of Object.entries(this._getters)) {
+      Object.defineProperty(this.getters, name, {
+        get: () => fn(this.state.__raw || this.state),
+        enumerable: true
+      });
+    }
+  }
+
+  /**
+   * Dispatch a named action
+   * @param {string} name — action name
+   * @param  {...any} args — payload
+   */
+  dispatch(name, ...args) {
+    const action = this._actions[name];
+    if (!action) {
+      console.warn(`zQuery Store: Unknown action "${name}"`);
+      return;
+    }
+
+    // Run middleware
+    for (const mw of this._middleware) {
+      const result = mw(name, args, this.state);
+      if (result === false) return; // blocked by middleware
+    }
+
+    if (this._debug) {
+      console.log(`%c[Store] ${name}`, 'color: #4CAF50; font-weight: bold;', ...args);
+    }
+
+    const result = action(this.state, ...args);
+    this._history.push({ action: name, args, timestamp: Date.now() });
+    return result;
+  }
+
+  /**
+   * Subscribe to changes on a specific state key
+   * @param {string|Function} keyOrFn — state key, or function for all changes
+   * @param {Function} [fn] — callback (value, oldValue, key)
+   * @returns {Function} — unsubscribe
+   */
+  subscribe(keyOrFn, fn) {
+    if (typeof keyOrFn === 'function') {
+      // Wildcard — listen to all changes
+      this._wildcards.add(keyOrFn);
+      return () => this._wildcards.delete(keyOrFn);
+    }
+
+    if (!this._subscribers.has(keyOrFn)) {
+      this._subscribers.set(keyOrFn, new Set());
+    }
+    this._subscribers.get(keyOrFn).add(fn);
+    return () => this._subscribers.get(keyOrFn)?.delete(fn);
+  }
+
+  /**
+   * Get current state snapshot (plain object)
+   */
+  snapshot() {
+    return JSON.parse(JSON.stringify(this.state.__raw || this.state));
+  }
+
+  /**
+   * Replace entire state
+   */
+  replaceState(newState) {
+    const raw = this.state.__raw || this.state;
+    for (const key of Object.keys(raw)) {
+      delete this.state[key];
+    }
+    Object.assign(this.state, newState);
+  }
+
+  /**
+   * Add middleware: fn(actionName, args, state) → false to block
+   */
+  use(fn) {
+    this._middleware.push(fn);
+    return this;
+  }
+
+  /**
+   * Get action history
+   */
+  get history() {
+    return [...this._history];
+  }
+
+  /**
+   * Reset state to initial values
+   */
+  reset(initialState) {
+    this.replaceState(initialState);
+    this._history = [];
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+let _stores = new Map();
+
+export function createStore(name, config) {
+  // If called with just config (no name), use 'default'
+  if (typeof name === 'object') {
+    config = name;
+    name = 'default';
+  }
+  const store = new Store(config);
+  _stores.set(name, store);
+  return store;
+}
+
+export function getStore(name = 'default') {
+  return _stores.get(name) || null;
+}