zero-query 1.0.0 → 1.0.2

package/cli/scaffold/ssr/app/components/not-found.js

@@ -7,7 +7,7 @@ export const notFound = {
         <h1>404</h1>
         <p class="subtitle">Page not found.</p>
         <p style="margin-top:1rem;">
-          <a href="/" style="color:var(--accent);">← Home</a>
+          <a z-link="/" style="color:var(--accent);">← Home</a>
         </p>
       </div>
     `;

package/cli/scaffold/ssr/app/routes.js

@@ -1,6 +1,8 @@
 // routes.js - Route definitions (shared between client and server)
 
 export const routes = [
-  { path: '/',     component: 'home-page'  },
-  { path: '/about', component: 'about-page' },
+  { path: '/',            component: 'home-page'  },
+  { path: '/blog',        component: 'blog-list'  },
+  { path: '/blog/:slug',  component: 'blog-post'  },
+  { path: '/about',       component: 'about-page' },
 ];

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);
@@ -57,13 +59,12 @@ body {
 
 /* -- Main content -- */
 z-outlet {
-  max-width: 800px;
+  display: block;
+  max-width: 1200px;
   margin: 2rem auto;
   padding: 0 1.5rem;
 }
 
-[z-cloak] { display: none !important; }
-
 .page-header {
   margin-bottom: var(--gap);
 }
@@ -92,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;
@@ -103,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,13 +20,14 @@
   <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>
 
   <!-- Main content - SSR output is injected here by the server -->
-  <z-outlet z-cloak></z-outlet>
+  <z-outlet></z-outlet>
 
   <footer class="footer">
     <small>Built with zQuery · SSR Scaffold</small>

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

@@ -17,9 +17,14 @@ import { createSSRApp } 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,43 +34,160 @@ 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 ---------------------------------------------------------
 
+/**
+ * Match a pathname to a route definition. Supports :param segments.
+ * Returns { component, params } or the not-found fallback.
+ */
 function matchRoute(pathname) {
-  const route = routes.find(r => r.path === pathname);
-  return route ? route.component : 'not-found';
+  for (const route of routes) {
+    const paramNames = [];
+    const pattern = route.path.replace(/:(\w+)/g, (_, name) => {
+      paramNames.push(name);
+      return '([^/]+)';
+    });
+    const match = new RegExp(`^${pattern}$`).exec(pathname);
+    if (match) {
+      const params = {};
+      paramNames.forEach((name, i) => { params[name] = match[i + 1]; });
+      return { component: route.component, params };
+    }
+  }
+  return { component: 'not-found', params: {} };
+}
+
+// --- 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',
+      };
+    }
+
+    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>.
+let shellCache = null;
+async function getShell() {
+  if (!shellCache) shellCache = await readFile(join(ROOT, 'index.html'), 'utf-8');
+  return shellCache;
+}
+
 async function render(pathname) {
-  const component = matchRoute(pathname);
-  const body = await app.renderToString(component);
-
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{{NAME}}</title>
-  <link rel="stylesheet" href="/global.css">
-</head>
-<body>
-  <nav class="navbar">
-    <span class="brand">⚡ {{NAME}}</span>
-    <div class="nav-links">
-${routes.map(r =>
-  `      <a href="${r.path}" class="nav-link${r.path === pathname ? ' active' : ''}">${
-    r.path === '/' ? 'Home' : r.path.slice(1)[0].toUpperCase() + r.path.slice(2)
-  }</a>`).join('\n')}
-    </div>
-  </nav>
-  <z-outlet>${body}</z-outlet>
-  <footer class="footer"><small>Built with zQuery · SSR</small></footer>
-</body>
-</html>`;
+  const { component, params } = matchRoute(pathname);
+  const props = getPropsForRoute(component, params);
+  const meta = getMetaForRoute(component, params, props);
+
+  // SSR render — pass server-fetched data as props to the component
+  const body = await app.renderToString(component, props);
+  const shell = await getShell();
+
+  // Inject SSR content into <z-outlet …>
+  let html = shell.replace(/(<z-outlet[^>]*>)(<\/z-outlet>)?/, `$1${body}</z-outlet>`);
+
+  // Inject page-specific <title> and meta tags for SEO / social sharing
+  html = html.replace(/<title>[^<]*<\/title>/, `<title>${meta.title}</title>`);
+  html = html.replace(
+    /<meta name="description" content="[^"]*">/,
+    `<meta name="description" content="${meta.description}">`
+  );
+  html = html.replace(
+    /<meta property="og:title" content="[^"]*">/,
+    `<meta property="og:title" content="${meta.title}">`
+  );
+  html = html.replace(
+    /<meta property="og:description" content="[^"]*">/,
+    `<meta property="og:description" content="${meta.description}">`
+  );
+  html = html.replace(
+    /<meta property="og:type" content="[^"]*">/,
+    `<meta property="og:type" content="${meta.ogType}">`
+  );
+
+  // Embed server data so the client can hydrate without re-fetching.
+  // Also include meta so client can update document.title on navigation.
+  const ssrData = JSON.stringify({ component, params, props, meta });
+  html = html.replace(
+    '</head>',
+    `<script>window.__SSR_DATA__=${ssrData};</script>\n</head>`
+  );
+
+  return html;
 }
 
 // --- Static files -----------------------------------------------------------
@@ -99,6 +221,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.0
+ * zQuery (zeroQuery) v1.0.2
  * 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;
@@ -6189,9 +6204,9 @@ $.validate       = validate;
 $.formatError    = formatError;
 
 // --- Meta ------------------------------------------------------------------
-$.version   = '1.0.0';
-$.libSize   = '~106 KB';
-$.unitTests = {"passed":1882,"failed":0,"total":1882,"suites":508,"duration":3548,"ok":true};
+$.version   = '1.0.2';
+$.libSize   = '~107 KB';
+$.unitTests = {"passed":1906,"failed":0,"total":1906,"suites":521,"duration":3744,"ok":true};
 $.meta      = {};              // populated at build time by CLI bundler
 
 $.noConflict = () => {