zero-query 1.0.1 → 1.0.5

package/index.d.ts

@@ -4,7 +4,7 @@
  * Lightweight modern frontend library - jQuery-like selectors, reactive
  * components, SPA router, state management, HTTP client & utilities.
  *
- * @version 1.0.1
+ * @version 1.0.5
  * @license MIT
  * @see https://z-query.com/docs
  */
@@ -46,8 +46,10 @@ export {
   NavigationContext,
   RouterConfig,
   RouterInstance,
+  RouteMatch,
   createRouter,
   getRouter,
+  matchRoute,
 } from './types/router';
 
 export {
@@ -146,7 +148,7 @@ export {
 import type { ZQueryCollection } from './types/collection';
 import type { reactive, Signal, signal, computed, effect, batch, untracked } from './types/reactive';
 import type { component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style } from './types/component';
-import type { createRouter, getRouter } from './types/router';
+import type { createRouter, getRouter, matchRoute } from './types/router';
 import type { createStore, getStore } from './types/store';
 import type { HttpClient } from './types/http';
 import type {
@@ -264,6 +266,7 @@ interface ZQueryStatic {
   // -- Router --------------------------------------------------------------
   router: typeof createRouter;
   getRouter: typeof getRouter;
+  matchRoute: typeof matchRoute;
 
   // -- Store ---------------------------------------------------------------
   store: typeof createStore;

package/index.js

@@ -12,7 +12,7 @@
 import { query, queryAll, ZQueryCollection } from './src/core.js';
 import { reactive, Signal, signal, computed, effect, batch, untracked } from './src/reactive.js';
 import { component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style } from './src/component.js';
-import { createRouter, getRouter } from './src/router.js';
+import { createRouter, getRouter, matchRoute } from './src/router.js';
 import { createStore, getStore } from './src/store.js';
 import { http } from './src/http.js';
 import { morph, morphElement } from './src/diff.js';
@@ -115,8 +115,9 @@ $.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
-$.router    = createRouter;
-$.getRouter = getRouter;
+$.router     = createRouter;
+$.getRouter  = getRouter;
+$.matchRoute = matchRoute;
 
 // --- Store -----------------------------------------------------------------
 $.store    = createStore;
@@ -214,7 +215,7 @@ export {
   component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style,
   morph, morphElement,
   safeEval,
-  createRouter, getRouter,
+  createRouter, getRouter, matchRoute,
   createStore, getStore,
   http,
   ZQueryError, ErrorCode, onError, reportError, guardCallback, guardAsync, validate, formatError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "1.0.1",
+  "version": "1.0.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",

package/src/component.js

@@ -678,13 +678,28 @@ class Component {
             if (el.contains(e.target)) continue;
           }
 
-          // Key modifiers - filter keyboard events by key
+          // Key modifiers - filter keyboard events by key.
+          // Named shortcuts map common names to their e.key values.
+          // Any modifier not recognised as a built-in behaviour, timing,
+          // or system modifier is matched against e.key (case-insensitive)
+          // so that arbitrary keys work: .a, .f1, .+, .0, .arrowup, etc.
           const _keyMap = { enter: 'Enter', escape: 'Escape', tab: 'Tab', space: ' ', delete: 'Delete|Backspace', up: 'ArrowUp', down: 'ArrowDown', left: 'ArrowLeft', right: 'ArrowRight' };
+          const _nonKeyMods = new Set(['prevent','stop','self','once','outside','capture','passive','debounce','throttle','ctrl','shift','alt','meta']);
           let keyFiltered = false;
-          for (const mod of modifiers) {
+          for (let mi = 0; mi < modifiers.length; mi++) {
+            const mod = modifiers[mi];
             if (_keyMap[mod]) {
               const keys = _keyMap[mod].split('|');
               if (!e.key || !keys.includes(e.key)) { keyFiltered = true; break; }
+            } else if (_nonKeyMods.has(mod)) {
+              continue;
+            } else if (/^\d+$/.test(mod) && mi > 0 && (modifiers[mi - 1] === 'debounce' || modifiers[mi - 1] === 'throttle')) {
+              // Numeric value following debounce/throttle — skip (it's a ms parameter)
+              continue;
+            } else {
+              // Dynamic key match — compare modifier against e.key
+              // Case-insensitive: .a matches 'a' and 'A', .f1 matches 'F1'
+              if (!e.key || e.key.toLowerCase() !== mod.toLowerCase()) { keyFiltered = true; break; }
             }
           }
           if (keyFiltered) continue;

package/src/router.js

@@ -195,24 +195,15 @@ class Router {
 
   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}$`);
-
+    const { regex, keys } = compilePath(route.path);
     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.
     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 });
+      const fb = compilePath(route.fallback);
+      this._routes.push({ ...route, path: route.fallback, _regex: fb.regex, _keys: fb.keys });
     }
 
     return this;
@@ -709,6 +700,64 @@ class Router {
 }
 
 
+// ---------------------------------------------------------------------------
+// Path compilation (shared by Router.add and matchRoute)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a route path pattern into a RegExp and param key list.
+ * Supports `:param` segments and `*` wildcard.
+ * @param {string} path - e.g. '/user/:id' or '/files/*'
+ * @returns {{ regex: RegExp, keys: string[] }}
+ */
+function compilePath(path) {
+  const keys = [];
+  const pattern = path
+    .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; })
+    .replace(/\*/g, '(.*)');
+  return { regex: new RegExp(`^${pattern}$`), keys };
+}
+
+// ---------------------------------------------------------------------------
+// Standalone route matcher (DOM-free — usable on server and client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a pathname against an array of route definitions.
+ * Returns `{ component, params }`.  If no route matches, falls back to the
+ * `fallback` component name (default `'not-found'`).
+ *
+ * This is the same matching logic the client-side router uses internally,
+ * extracted so SSR servers can resolve URLs without the DOM.
+ *
+ * @param {Array<{ path: string, component: string, fallback?: string }>} routes
+ * @param {string} pathname - URL path to match, e.g. '/blog/my-post'
+ * @param {string} [fallback='not-found'] - Component name when nothing matches
+ * @returns {{ component: string, params: Record<string, string> }}
+ */
+export function matchRoute(routes, pathname, fallback = 'not-found') {
+  for (const route of routes) {
+    const { regex, keys } = compilePath(route.path);
+    const m = pathname.match(regex);
+    if (m) {
+      const params = {};
+      keys.forEach((key, i) => { params[key] = m[i + 1]; });
+      return { component: route.component, params };
+    }
+    // Per-route fallback alias (same as Router.add)
+    if (route.fallback) {
+      const fb = compilePath(route.fallback);
+      const fbm = pathname.match(fb.regex);
+      if (fbm) {
+        const params = {};
+        fb.keys.forEach((key, i) => { params[key] = fbm[i + 1]; });
+        return { component: route.component, params };
+      }
+    }
+  }
+  return { component: fallback, params: {} };
+}
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------

package/src/ssr.js

@@ -280,6 +280,103 @@ class SSRApp {
   </body>
 </html>`;
   }
+
+  /**
+   * Render a component into an existing HTML shell template.
+   *
+   * Unlike renderPage() which generates a full HTML document from scratch,
+   * renderShell() takes your own index.html (with nav, footer, custom markup)
+   * and injects the SSR-rendered component body plus metadata into it.
+   *
+   * Handles:
+   *   - Component rendering into <z-outlet>
+   *   - <title> replacement
+   *   - <meta name="description"> replacement
+   *   - Open Graph meta tag replacement (og:title, og:description, og:type, etc.)
+   *   - window.__SSR_DATA__ hydration script injection
+   *
+   * @param {string} shell - HTML template string (your index.html)
+   * @param {object} options
+   * @param {string} options.component - registered component name to render
+   * @param {object} [options.props] - props passed to the component
+   * @param {string} [options.title] - page title (replaces <title>)
+   * @param {string} [options.description] - meta description (replaces <meta name="description">)
+   * @param {object} [options.og] - Open Graph tags to replace (e.g. { title, description, type, image })
+   * @param {any}    [options.ssrData] - data to embed as window.__SSR_DATA__ for client hydration
+   * @param {object} [options.renderOptions] - options passed to renderToString (hydrate, mode)
+   * @returns {Promise<string>} - the shell with SSR content and metadata injected
+   */
+  async renderShell(shell, options = {}) {
+    const {
+      component: comp,
+      props = {},
+      title,
+      description,
+      og,
+      ssrData,
+      renderOptions,
+    } = options;
+
+    // Render the component
+    let body = '';
+    if (comp) {
+      try {
+        body = await this.renderToString(comp, props, renderOptions);
+      } catch (err) {
+        reportError(ErrorCode.SSR_PAGE, `renderShell failed for component "${comp}"`, { component: comp }, err);
+        body = `<!-- SSR error: ${_escapeHtml(err.message)} -->`;
+      }
+    }
+
+    let html = shell;
+
+    // Inject SSR body into <z-outlet>
+    // Use a replacer function to avoid $ substitution patterns in body
+    html = html.replace(/(<z-outlet[^>]*>)([\s\S]*?)(<\/z-outlet>)?/, (_, open) => `${open}${body}</z-outlet>`);
+
+    // Replace <title>
+    if (title != null) {
+      const safeTitle = _escapeHtml(title);
+      html = html.replace(/<title>[^<]*<\/title>/, () => `<title>${safeTitle}</title>`);
+    }
+
+    // Replace <meta name="description">
+    if (description != null) {
+      const safeDesc = _escapeHtml(description);
+      html = html.replace(
+        /<meta\s+name="description"\s+content="[^"]*">/,
+        () => `<meta name="description" content="${safeDesc}">`
+      );
+    }
+
+    // Replace Open Graph meta tags
+    if (og) {
+      for (const [key, value] of Object.entries(og)) {
+        // Sanitize key: allow only safe OG property characters (alphanumeric, hyphens, underscores, colons)
+        const safeKey = key.replace(/[^a-zA-Z0-9_:\-]/g, '');
+        if (!safeKey) continue;
+        const escaped = _escapeHtml(String(value));
+        // Escape key for use in RegExp to prevent ReDoS
+        const escapedKey = safeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`<meta\\s+property="og:${escapedKey}"\\s+content="[^"]*">`);
+        if (pattern.test(html)) {
+          html = html.replace(pattern, () => `<meta property="og:${safeKey}" content="${escaped}">`);
+        } else {
+          // Tag doesn't exist — inject before </head>
+          html = html.replace('</head>', () => `<meta property="og:${safeKey}" content="${escaped}">\n</head>`);
+        }
+      }
+    }
+
+    // Inject hydration data as window.__SSR_DATA__
+    if (ssrData !== undefined) {
+      // Escape </script> and <!-- sequences to prevent breaking out of the script tag
+      const json = JSON.stringify(ssrData).replace(/<\//g, '<\\/').replace(/<!--/g, '<\\!--');
+      html = html.replace('</head>', () => `<script>window.__SSR_DATA__=${json};</script>\n</head>`);
+    }
+
+    return html;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -316,3 +413,6 @@ export function renderToString(definition, props = {}) {
 export function escapeHtml(str) {
   return _escapeHtml(String(str));
 }
+
+// Re-export matchRoute so SSR servers can import from 'zero-query/ssr'
+export { matchRoute } from './router.js';