zero-query 1.0.1 → 1.0.5

package/cli/scaffold/ssr/global.css

@@ -49,6 +49,8 @@ body {
   padding: 0.4rem 0.8rem;
   border-radius: var(--radius);
   transition: color 0.2s, background 0.2s;
+  cursor: pointer;
+  user-select: none;
 }
 .nav-link:hover, .nav-link.active {
   color: var(--accent);
@@ -58,7 +60,7 @@ body {
 /* -- Main content -- */
 z-outlet {
   display: block;
-  max-width: 800px;
+  max-width: 1200px;
   margin: 2rem auto;
   padding: 0 1.5rem;
 }
@@ -91,6 +93,15 @@ z-outlet {
   border-radius: 4px;
   font-size: 0.9em;
 }
+.card a {
+  color: var(--accent);
+  text-decoration: none;
+  transition: color 0.15s;
+}
+.card a:hover {
+  color: var(--accent-hover);
+  text-decoration: underline;
+}
 
 .badge {
   display: inline-block;
@@ -102,6 +113,111 @@ z-outlet {
 .badge-ssr { background: rgba(0,212,255,0.15); color: var(--accent); }
 .badge-csr { background: rgba(255,165,0,0.15); color: #ffa500; }
 
+/* -- Blog Grid -- */
+.blog-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+  gap: var(--gap);
+}
+
+.blog-card {
+  display: block;
+  text-decoration: none;
+  color: inherit;
+  background: var(--surface);
+  border: 1px solid rgba(255,255,255,0.06);
+  border-radius: var(--radius);
+  padding: 1.5rem;
+  transition: border-color 0.2s, transform 0.2s;
+  cursor: pointer;
+}
+.blog-card:hover {
+  border-color: rgba(0, 212, 255, 0.25);
+  transform: translateY(-2px);
+}
+
+.blog-card-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 0.75rem;
+}
+
+.blog-date {
+  font-size: 0.8em;
+  color: var(--muted);
+}
+
+.blog-title {
+  font-size: 1.1rem;
+  margin-bottom: 0.5rem;
+  color: var(--text);
+}
+
+.blog-summary {
+  color: var(--muted);
+  font-size: 0.9rem;
+  line-height: 1.6;
+}
+
+/* -- Blog Post Detail -- */
+.back-link {
+  display: inline-block;
+  color: var(--accent);
+  font-size: 0.9rem;
+  margin-bottom: 1rem;
+  transition: opacity 0.15s;
+  text-decoration: none;
+  cursor: pointer;
+}
+.back-link:hover { opacity: 0.75; }
+
+.blog-post-meta {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-top: 0.5rem;
+}
+
+.blog-post-body {
+  background: var(--surface);
+  border: 1px solid rgba(255,255,255,0.06);
+  border-radius: var(--radius);
+  padding: 2rem;
+  line-height: 1.8;
+  font-size: 0.95rem;
+}
+.blog-post-body h4 {
+  color: var(--accent);
+  margin: 1.5rem 0 0.75rem;
+  font-size: 1.05rem;
+}
+.blog-post-body h4:first-child { margin-top: 0; }
+.blog-post-body ul, .blog-post-body ol {
+  padding-left: 1.5rem;
+  margin: 0.5rem 0;
+}
+.blog-post-body li { margin-bottom: 0.4rem; }
+.blog-post-body pre {
+  background: rgba(0,0,0,0.3);
+  border-radius: var(--radius);
+  padding: 1rem 1.25rem;
+  overflow-x: auto;
+  margin: 0.75rem 0;
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+.blog-post-body code {
+  background: rgba(255,255,255,0.06);
+  padding: 0.15em 0.4em;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+.blog-post-body pre code {
+  background: none;
+  padding: 0;
+}
+
 /* -- Footer -- */
 .footer {
   text-align: center;

package/cli/scaffold/ssr/index.html

@@ -4,6 +4,11 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>{{NAME}}</title>
+  <meta name="description" content="">
+  <meta property="og:title" content="{{NAME}}">
+  <meta property="og:description" content="">
+  <meta property="og:type" content="website">
+  <meta name="robots" content="index, follow">
   <base href="/">
   <link rel="stylesheet" href="global.css">
   <script src="zquery.min.js"></script>
@@ -15,8 +20,9 @@
   <nav class="navbar">
     <span class="brand">⚡ {{NAME}}</span>
     <div class="nav-links">
-      <a z-link="/" class="nav-link">Home</a>
-      <a z-link="/about" class="nav-link">About</a>
+      <a z-link="/" class="nav-link" z-active-route="/" z-active-exact>Home</a>
+      <a z-link="/blog" class="nav-link" z-active-route="/blog">Blog</a>
+      <a z-link="/about" class="nav-link" z-active-route="/about">About</a>
     </div>
   </nav>
 

package/cli/scaffold/ssr/server/data/posts.js

@@ -0,0 +1,144 @@
+// server/data/posts.js - Blog post data
+//
+// Simulates a database or CMS. In a real app you'd fetch from a DB,
+// headless CMS, or markdown files. The server imports this data and
+// passes it as props to blog components during SSR.
+
+export const posts = [
+  {
+    slug: 'why-ssr-matters',
+    title: 'Why Server-Side Rendering Matters',
+    date: '2025-12-15',
+    tag: 'SSR',
+    summary:
+      'SSR delivers fully rendered HTML to the browser, improving first contentful paint, SEO indexability, and perceived performance on slower connections.',
+    body: `
+      <p>Server-Side Rendering (SSR) generates the full HTML for a page on the server
+      before sending it to the browser. Instead of shipping an empty shell and waiting
+      for JavaScript to populate it, the user sees content immediately.</p>
+
+      <h4>Key Benefits</h4>
+      <ul>
+        <li><strong>Faster First Paint</strong> — HTML arrives ready to display.
+        No waiting for JS bundles to download and execute.</li>
+        <li><strong>SEO Friendly</strong> — Search engine crawlers see complete
+        content without running JavaScript.</li>
+        <li><strong>Social Sharing</strong> — Open Graph meta tags are present in
+        the initial response, so link previews work everywhere.</li>
+        <li><strong>Accessibility</strong> — Content is available even if JS fails
+        to load or is disabled.</li>
+      </ul>
+
+      <h4>The Trade-Off</h4>
+      <p>SSR adds server-side compute cost per request. Strategies like render
+      caching, edge deployment, and stale-while-revalidate headers help keep
+      response times low while maintaining the benefits of dynamic rendering.</p>
+    `,
+  },
+  {
+    slug: 'hydration-explained',
+    title: 'Hydration: Picking Up Where the Server Left Off',
+    date: '2025-12-20',
+    tag: 'Architecture',
+    summary:
+      'After the server sends HTML, the client "hydrates" the page — attaching event listeners and reactive state so the SPA takes over without a full re-render.',
+    body: `
+      <p>Hydration is the process where the client-side framework takes ownership
+      of server-rendered HTML. The DOM is already there — hydration wires up event
+      handlers, reactive state, and component lifecycles on top of it.</p>
+
+      <h4>How It Works in zQuery</h4>
+      <ol>
+        <li>The server renders a component to HTML with <code>app.renderToString()</code>,
+        adding a <code>data-zq-ssr</code> marker.</li>
+        <li>The HTML is injected into the page shell and sent to the browser.</li>
+        <li>The client loads the same component definitions and registers them
+        with <code>$.component()</code>.</li>
+        <li>The router detects the SSR marker and hydrates instead of re-rendering,
+        preserving the existing DOM while activating reactivity.</li>
+      </ol>
+
+      <h4>Why This Matters</h4>
+      <p>Without hydration, the client would discard the server HTML and re-render
+      from scratch — causing a flash of empty content. Hydration gives you the best
+      of both worlds: fast server-rendered first paint with full client interactivity.</p>
+    `,
+  },
+  {
+    slug: 'shared-components',
+    title: 'Shared Components Across Client and Server',
+    date: '2026-01-05',
+    tag: 'Components',
+    summary:
+      'Write your component once and use it everywhere. The same definition object that powers client rendering can be imported by the SSR server to produce identical markup.',
+    body: `
+      <p>In zQuery, a component is a plain JavaScript object with <code>state</code>,
+      <code>render()</code>, and optional lifecycle hooks. This simple contract means
+      the same file works on both sides:</p>
+
+      <pre><code>// components/greeting.js
+export const greeting = {
+  state: () => ({ name: 'World' }),
+  render() {
+    return \`&lt;h1&gt;Hello, \${this.state.name}!&lt;/h1&gt;\`;
+  }
+};</code></pre>
+
+      <h4>Client</h4>
+      <pre><code>import { greeting } from './components/greeting.js';
+$.component('greeting', greeting);</code></pre>
+
+      <h4>Server</h4>
+      <pre><code>import { greeting } from '../app/components/greeting.js';
+app.component('greeting', greeting);
+const html = await app.renderToString('greeting', { name: 'Tony' });</code></pre>
+
+      <p>No special file conventions, no build-time transforms. Just JavaScript
+      modules shared between environments.</p>
+    `,
+  },
+  {
+    slug: 'ssr-caching-strategies',
+    title: 'Caching Strategies for SSR Pages',
+    date: '2026-01-18',
+    tag: 'Performance',
+    summary:
+      'Combine stale-while-revalidate headers, in-memory render caching, and CDN edge caching to serve SSR pages at static-site speed without sacrificing freshness.',
+    body: `
+      <p>SSR is powerful but adds per-request compute. Smart caching lets you keep
+      the dynamic benefits while serving at near-static speed.</p>
+
+      <h4>Layer 1: In-Memory Cache</h4>
+      <p>Cache rendered HTML in a <code>Map</code> keyed by route. Set a TTL
+      (e.g. 60 seconds) and serve cached responses until they expire. Simple and
+      effective for moderate traffic.</p>
+
+      <h4>Layer 2: HTTP Cache Headers</h4>
+      <pre><code>Cache-Control: public, s-maxage=60, stale-while-revalidate=300</code></pre>
+      <p>This tells CDNs to serve cached content for 60s, then revalidate in the
+      background for up to 5 minutes. Users always get a fast response.</p>
+
+      <h4>Layer 3: CDN Edge Caching</h4>
+      <p>Deploy behind a CDN (Cloudflare, Vercel Edge, Fastly) so cached pages are
+      served from the nearest edge node. Combine with geographic routing for
+      sub-100ms global TTFB.</p>
+
+      <h4>When to Skip Caching</h4>
+      <p>User-specific pages (dashboards, settings) shouldn't be edge-cached.
+      Use <code>Cache-Control: private</code> and rely on in-memory caching
+      or skip caching entirely for authenticated routes.</p>
+    `,
+  },
+];
+
+/** Find a single post by slug. Returns undefined if not found. */
+export function getPostBySlug(slug) {
+  return posts.find(p => p.slug === slug);
+}
+
+/** Return all posts (summary only — no body). */
+export function getAllPosts() {
+  return posts.map(({ slug, title, date, tag, summary }) => ({
+    slug, title, date, tag, summary,
+  }));
+}

package/cli/scaffold/ssr/server/index.js

@@ -12,14 +12,19 @@ import { createServer } from 'node:http';
 import { readFile } from 'node:fs/promises';
 import { join, extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createSSRApp } from 'zero-query/ssr';
+import { createSSRApp, matchRoute } from 'zero-query/ssr';
 
 // Shared component definitions - same ones the client registers
 import { homePage }  from '../app/components/home.js';
 import { aboutPage } from '../app/components/about.js';
+import { blogList }  from '../app/components/blog/index.js';
+import { blogPost }  from '../app/components/blog/post.js';
 import { notFound }  from '../app/components/not-found.js';
 import { routes }    from '../app/routes.js';
 
+// Server-side data — simulates a database or CMS
+import { getAllPosts, getPostBySlug } from './data/posts.js';
+
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT = join(__dirname, '..');
 const PORT = parseInt(process.env.PORT || '3000', 10);
@@ -29,20 +34,91 @@ const PORT = parseInt(process.env.PORT || '3000', 10);
 const app = createSSRApp();
 app.component('home-page',  homePage);
 app.component('about-page', aboutPage);
+app.component('blog-list',  blogList);
+app.component('blog-post',  blogPost);
 app.component('not-found',  notFound);
 
-// --- Route matching ---------------------------------------------------------
+// --- Server-side data fetching ----------------------------------------------
+
+/**
+ * Fetch data for a matched route. This is where you'd query a database,
+ * call an API, or read from the filesystem in a real application.
+ * The returned object is passed as props to the component during SSR.
+ */
+function getPropsForRoute(component, params) {
+  switch (component) {
+    case 'blog-list':
+      return { posts: getAllPosts() };
+    case 'blog-post':
+      return { post: getPostBySlug(params.slug) || null };
+    default:
+      return {};
+  }
+}
+
+// --- SEO metadata per route -------------------------------------------------
+
+/**
+ * Return page-specific metadata for SEO, social sharing, and browser tabs.
+ * The server injects these into the HTML shell's <head> before sending.
+ *
+ * In a real app you'd pull this from a CMS or database alongside the content.
+ * Open Graph tags ensure rich link previews on social media.
+ */
+function getMetaForRoute(component, params, props) {
+  const base = {
+    title: '{{NAME}}',
+    description: 'A zQuery SSR application.',
+    ogType: 'website',
+  };
+
+  switch (component) {
+    case 'home-page':
+      return {
+        ...base,
+        title: '{{NAME}} — Home',
+        description: 'A server-rendered application built with zQuery. Fast first paint, SEO-friendly, zero dependencies.',
+      };
+
+    case 'blog-list':
+      return {
+        ...base,
+        title: 'Blog — {{NAME}}',
+        description: 'Articles on server-side rendering, hydration, shared components, and modern web architecture.',
+      };
+
+    case 'blog-post': {
+      const post = props.post;
+      if (!post) return { ...base, title: 'Post Not Found — {{NAME}}' };
+      return {
+        ...base,
+        title: `${post.title} — {{NAME}}`,
+        description: post.summary,
+        ogType: 'article',
+      };
+    }
 
-function matchRoute(pathname) {
-  const route = routes.find(r => r.path === pathname);
-  return route ? route.component : 'not-found';
+    case 'about-page':
+      return {
+        ...base,
+        title: 'About — {{NAME}}',
+        description: 'Learn about zQuery — a zero-dependency frontend micro-library for reactive components, routing, SSR, and state management.',
+      };
+
+    default:
+      return {
+        ...base,
+        title: 'Page Not Found — {{NAME}}',
+        description: 'The page you\'re looking for doesn\'t exist.',
+      };
+  }
 }
 
 // --- Render a full HTML page ------------------------------------------------
 
 // Read the index.html shell once at startup — it already has z-link nav,
 // client scripts (zquery.min.js + app/app.js), and the <z-outlet> tag.
-// On each request we just inject the SSR body into <z-outlet>.
+// On each request we render the matched component into the shell.
 let shellCache = null;
 async function getShell() {
   if (!shellCache) shellCache = await readFile(join(ROOT, 'index.html'), 'utf-8');
@@ -50,23 +126,22 @@ async function getShell() {
 }
 
 async function render(pathname) {
-  const component = matchRoute(pathname);
-  const body = await app.renderToString(component);
-  const shell = await getShell();
-
-  // Inject SSR content into <z-outlet …> and add active class to nav
-  let html = shell.replace(/(<z-outlet[^>]*>)(<\/z-outlet>)?/, `$1${body}</z-outlet>`);
-
-  // Mark the active nav link for the current route
-  html = html.replace(
-    /(<a\s+z-link="([^"]*)"[^>]*class="nav-link)(">)/g,
-    (match, before, href, after) =>
-      href === pathname
-        ? `${before} active${after}`
-        : `${before}${after}`
-  );
-
-  return html;
+  const { component, params } = matchRoute(routes, pathname);
+  const props = getPropsForRoute(component, params);
+  const meta = getMetaForRoute(component, params, props);
+
+  return app.renderShell(await getShell(), {
+    component,
+    props,
+    title: meta.title,
+    description: meta.description,
+    og: {
+      title: meta.title,
+      description: meta.description,
+      type: meta.ogType,
+    },
+    ssrData: { component, params, props, meta },
+  });
 }
 
 // --- Static files -----------------------------------------------------------
@@ -100,6 +175,25 @@ createServer(async (req, res) => {
   // Static assets (CSS, images, etc.)
   if (pathname !== '/' && await serveStatic(res, pathname)) return;
 
+  // --- JSON API for client-side navigation ----------------------------------
+  // The client fetches data here when navigating via SPA (after initial SSR).
+  // In a real app, these would query a database or external API.
+
+  if (pathname === '/api/posts') {
+    const json = JSON.stringify(getAllPosts());
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(json);
+    return;
+  }
+
+  const postMatch = /^\/api\/posts\/([^/]+)$/.exec(pathname);
+  if (postMatch) {
+    const post = getPostBySlug(postMatch[1]) || null;
+    res.writeHead(post ? 200 : 404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(post));
+    return;
+  }
+
   // SSR route
   try {
     const html = await render(pathname);

package/dist/zquery.js

@@ -1,5 +1,5 @@
 /**
- * zQuery (zeroQuery) v1.0.1
+ * zQuery (zeroQuery) v1.0.5
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman - MIT License
@@ -3498,13 +3498,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;
@@ -4455,24 +4470,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;
@@ -4969,6 +4975,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> }}
+ */
+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
 // ---------------------------------------------------------------------------
@@ -6124,8 +6188,9 @@ $.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
-$.router    = createRouter;
-$.getRouter = getRouter;
+$.router     = createRouter;
+$.getRouter  = getRouter;
+$.matchRoute = matchRoute;
 
 // --- Store -----------------------------------------------------------------
 $.store    = createStore;
@@ -6189,9 +6254,9 @@ $.validate       = validate;
 $.formatError    = formatError;
 
 // --- Meta ------------------------------------------------------------------
-$.version   = '1.0.1';
-$.libSize   = '~106 KB';
-$.unitTests = {"passed":1882,"failed":0,"total":1882,"suites":508,"duration":3350,"ok":true};
+$.version   = '1.0.5';
+$.libSize   = '~107 KB';
+$.unitTests = {"passed":1931,"failed":0,"total":1931,"suites":523,"duration":3815,"ok":true};
 $.meta      = {};              // populated at build time by CLI bundler
 
 $.noConflict = () => {