zero-query 1.0.2 → 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.2
+ * @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.2",
+  "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/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';

package/tests/router.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { createRouter, getRouter } from '../src/router.js';
+import { createRouter, getRouter, matchRoute } from '../src/router.js';
 import { component } from '../src/component.js';
 
 // Register stub components used in route definitions so mount() doesn't throw
@@ -809,6 +809,70 @@ describe('Router - navigation chaining', () => {
 });
 
 
+// ---------------------------------------------------------------------------
+// matchRoute - standalone route matcher (DOM-free)
+// ---------------------------------------------------------------------------
+
+describe('matchRoute', () => {
+  const routes = [
+    { path: '/',            component: 'home-page'  },
+    { path: '/blog',        component: 'blog-list'  },
+    { path: '/blog/:slug',  component: 'blog-post'  },
+    { path: '/user/:id',    component: 'user-page'  },
+    { path: '/files/*',     component: 'file-browser' },
+  ];
+
+  it('matches a static route', () => {
+    expect(matchRoute(routes, '/')).toEqual({ component: 'home-page', params: {} });
+    expect(matchRoute(routes, '/blog')).toEqual({ component: 'blog-list', params: {} });
+  });
+
+  it('matches a parameterized route', () => {
+    expect(matchRoute(routes, '/blog/hello-world')).toEqual({
+      component: 'blog-post',
+      params: { slug: 'hello-world' },
+    });
+  });
+
+  it('matches multiple params', () => {
+    const r = [{ path: '/user/:id/post/:pid', component: 'user-post' }];
+    expect(matchRoute(r, '/user/42/post/7')).toEqual({
+      component: 'user-post',
+      params: { id: '42', pid: '7' },
+    });
+  });
+
+  it('matches wildcard routes', () => {
+    const result = matchRoute(routes, '/files/docs/readme.md');
+    expect(result.component).toBe('file-browser');
+  });
+
+  it('returns fallback when nothing matches', () => {
+    expect(matchRoute(routes, '/nope')).toEqual({ component: 'not-found', params: {} });
+  });
+
+  it('accepts a custom fallback component name', () => {
+    expect(matchRoute(routes, '/nope', '404-page')).toEqual({ component: '404-page', params: {} });
+  });
+
+  it('matches first route when multiple could match', () => {
+    const r = [
+      { path: '/a', component: 'first' },
+      { path: '/a', component: 'second' },
+    ];
+    expect(matchRoute(r, '/a').component).toBe('first');
+  });
+
+  it('handles per-route fallback aliases', () => {
+    const r = [
+      { path: '/docs/:section', component: 'docs-page', fallback: '/docs' },
+    ];
+    expect(matchRoute(r, '/docs/intro')).toEqual({ component: 'docs-page', params: { section: 'intro' } });
+    expect(matchRoute(r, '/docs')).toEqual({ component: 'docs-page', params: {} });
+  });
+});
+
+
 // ---------------------------------------------------------------------------
 // Hash mode path parsing
 // ---------------------------------------------------------------------------

package/tests/ssr.test.js

@@ -693,3 +693,178 @@ describe('escapeHtml (exported)', () => {
     expect(escapeHtml(42)).toBe('42');
   });
 });
+
+
+// ---------------------------------------------------------------------------
+// SSRApp - renderShell
+// ---------------------------------------------------------------------------
+
+describe('SSRApp - renderShell', () => {
+  const shell = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <title>Default Title</title>
+  <meta name="description" content="default desc">
+  <meta property="og:title" content="Default OG">
+  <meta property="og:description" content="">
+  <meta property="og:type" content="website">
+</head>
+<body>
+  <z-outlet></z-outlet>
+</body>
+</html>`;
+
+  let app;
+  beforeEach(() => {
+    app = createSSRApp();
+    app.component('test-page', {
+      state: () => ({ greeting: 'Hello' }),
+      render() { return `<h1>${this.state.greeting}</h1>`; }
+    });
+  });
+
+  it('renders a component into <z-outlet>', async () => {
+    const html = await app.renderShell(shell, { component: 'test-page' });
+    expect(html).toContain('<z-outlet><test-page data-zq-ssr><h1>Hello</h1></test-page></z-outlet>');
+  });
+
+  it('replaces the <title> tag', async () => {
+    const html = await app.renderShell(shell, { component: 'test-page', title: 'My App — Home' });
+    expect(html).toContain('<title>My App — Home</title>');
+    expect(html).not.toContain('Default Title');
+  });
+
+  it('replaces the meta description', async () => {
+    const html = await app.renderShell(shell, { component: 'test-page', description: 'A great page' });
+    expect(html).toContain('<meta name="description" content="A great page">');
+    expect(html).not.toContain('default desc');
+  });
+
+  it('replaces existing Open Graph tags', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      og: { title: 'OG Title', description: 'OG Desc', type: 'article' },
+    });
+    expect(html).toContain('<meta property="og:title" content="OG Title">');
+    expect(html).toContain('<meta property="og:description" content="OG Desc">');
+    expect(html).toContain('<meta property="og:type" content="article">');
+  });
+
+  it('injects new OG tags when they do not exist in the shell', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      og: { image: 'https://example.com/img.png' },
+    });
+    expect(html).toContain('<meta property="og:image" content="https://example.com/img.png">');
+  });
+
+  it('injects window.__SSR_DATA__ when ssrData is provided', async () => {
+    const data = { component: 'test-page', params: {}, props: {} };
+    const html = await app.renderShell(shell, { component: 'test-page', ssrData: data });
+    expect(html).toContain('window.__SSR_DATA__=');
+    expect(html).toContain('"component":"test-page"');
+    // Script is injected before </head>
+    expect(html.indexOf('__SSR_DATA__')).toBeLessThan(html.indexOf('</head>'));
+  });
+
+  it('does not inject ssrData when not provided', async () => {
+    const html = await app.renderShell(shell, { component: 'test-page' });
+    expect(html).not.toContain('__SSR_DATA__');
+  });
+
+  it('escapes title and description for XSS safety', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      title: '<script>alert("xss")</script>',
+      description: '"injected" & <dangerous>',
+    });
+    expect(html).toContain('&lt;script&gt;');
+    expect(html).toContain('&quot;injected&quot; &amp; &lt;dangerous&gt;');
+    expect(html).not.toContain('<script>alert');
+  });
+
+  it('leaves title and description alone when not provided', async () => {
+    const html = await app.renderShell(shell, { component: 'test-page' });
+    expect(html).toContain('<title>Default Title</title>');
+    expect(html).toContain('content="default desc"');
+  });
+
+  it('passes props to the rendered component', async () => {
+    app.component('greeting-page', {
+      render() { return `<p>Hi ${this.props.name}</p>`; }
+    });
+    const html = await app.renderShell(shell, { component: 'greeting-page', props: { name: 'Tony' } });
+    expect(html).toContain('<p>Hi Tony</p>');
+  });
+
+  it('passes renderOptions through to renderToString', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      renderOptions: { hydrate: false },
+    });
+    expect(html).toContain('<test-page><h1>Hello</h1></test-page>');
+    expect(html).not.toContain('data-zq-ssr');
+  });
+
+  it('handles a missing component gracefully', async () => {
+    const html = await app.renderShell(shell, { component: 'nonexistent' });
+    expect(html).toContain('<!-- SSR error:');
+  });
+
+  it('returns the shell untouched when no options are provided', async () => {
+    const html = await app.renderShell(shell);
+    expect(html).toContain('<title>Default Title</title>');
+    expect(html).toContain('<z-outlet></z-outlet>');
+  });
+
+  it('escapes </script> in ssrData to prevent script injection', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      ssrData: { payload: '</script><script>alert(1)</script>' },
+    });
+    expect(html).not.toContain('</script><script>alert(1)');
+    expect(html).toContain('<\\/script>');
+    // The JSON should still be parseable when unescaped
+    const match = html.match(/window\.__SSR_DATA__=(.+?);/);
+    expect(match).toBeTruthy();
+  });
+
+  it('escapes <!-- in ssrData to prevent HTML comment injection', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      ssrData: { payload: '<!-- injected -->' },
+    });
+    expect(html).not.toContain('<!-- injected');
+    expect(html).toContain('<\\!--');
+  });
+
+  it('sanitizes OG keys to prevent ReDoS and attribute injection', async () => {
+    const html = await app.renderShell(shell, {
+      component: 'test-page',
+      og: {
+        'title" onload="alert(1)': 'attack',   // attribute breakout attempt
+        'valid-key': 'safe value',
+        '': 'empty key should be skipped',       // empty after sanitization
+      },
+    });
+    // Attribute injection should be neutralized (quotes stripped from key)
+    expect(html).not.toContain('onload=');
+    expect(html).toContain('og:titleonloadalert1');
+    // Valid key should work fine
+    expect(html).toContain('og:valid-key');
+    expect(html).toContain('safe value');
+    // Empty key should be skipped
+    const emptyOgCount = (html.match(/og:""/g) || []).length;
+    expect(emptyOgCount).toBe(0);
+  });
+
+  it('handles $ substitution patterns in component output safely', async () => {
+    app.component('dollar-page', {
+      render() { return "<p>Price: $1.00 and $' and $` tricks</p>"; }
+    });
+    const html = await app.renderShell(shell, { component: 'dollar-page' });
+    expect(html).toContain("$1.00");
+    expect(html).toContain("$'");
+    expect(html).toContain("$`");
+  });
+});

package/types/router.d.ts

@@ -163,3 +163,28 @@ export function createRouter(config: RouterConfig): RouterInstance;
 
 /** Get the currently active router instance. */
 export function getRouter(): RouterInstance | null;
+
+/** Result of matching a URL path against route definitions. */
+export interface RouteMatch {
+  /** The matched component name, or the fallback if nothing matched. */
+  component: string;
+  /** Parsed `:param` values from the URL. */
+  params: Record<string, string>;
+}
+
+/**
+ * Match a pathname against an array of route definitions.
+ * Returns `{ component, params }`. If no route matches, returns the
+ * fallback component (default `'not-found'`).
+ *
+ * DOM-free — works on both server and client.
+ *
+ * @param routes - Array of route definitions with `path` and `component`.
+ * @param pathname - URL path to match, e.g. `'/blog/my-post'`.
+ * @param fallback - Component name when nothing matches (default `'not-found'`).
+ */
+export function matchRoute(
+  routes: RouteDefinition[],
+  pathname: string,
+  fallback?: string,
+): RouteMatch;

package/types/ssr.d.ts

@@ -51,6 +51,36 @@ export interface SSRApp {
       og?: Record<string, string>;
     };
   }): Promise<string>;
+
+  /**
+   * Render a component into an existing HTML shell template.
+   *
+   * Unlike `renderPage()` which generates a full document from scratch,
+   * `renderShell()` takes your own `index.html` (with nav, footer, custom
+   * markup) and injects the SSR-rendered component body plus metadata.
+   *
+   * Handles `<z-outlet>` injection, `<title>` replacement, meta description,
+   * Open Graph tags, and `window.__SSR_DATA__` hydration data.
+   *
+   * @param shell - HTML template string (your index.html content).
+   * @param options - Rendering and metadata options.
+   */
+  renderShell(shell: string, options?: {
+    /** Registered component name to render into `<z-outlet>`. */
+    component?: string;
+    /** Props passed to the component. */
+    props?: Record<string, any>;
+    /** Page title — replaces `<title>`. */
+    title?: string;
+    /** Meta description — replaces `<meta name="description">`. */
+    description?: string;
+    /** Open Graph tags to replace or inject (e.g. `{ title, description, type, image }`). */
+    og?: Record<string, string>;
+    /** Data embedded as `window.__SSR_DATA__` for client-side hydration. */
+    ssrData?: any;
+    /** Options passed through to `renderToString()` (hydrate, mode). */
+    renderOptions?: { hydrate?: boolean; mode?: 'html' | 'fragment' };
+  }): Promise<string>;
 }
 
 /** Create an SSR application instance. */
@@ -67,3 +97,6 @@ export function renderToString(definition: ComponentDefinition, props?: Record<s
  * Escape HTML entities - exposed for use in SSR templates.
  */
 export function escapeHtml(str: string): string;
+
+// Re-exported from router for SSR server convenience
+export { matchRoute, RouteMatch } from './router';