npm - zero-query - Versions diffs - 1.0.1 → 1.0.5 - Mend

zero-query 1.0.1 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/README.md +50 -9
package/cli/help.js +2 -1
package/cli/scaffold/default/app/app.js +3 -6
package/cli/scaffold/default/global.css +12 -3
package/cli/scaffold/default/index.html +8 -8
package/cli/scaffold/minimal/app/app.js +3 -9
package/cli/scaffold/minimal/global.css +12 -3
package/cli/scaffold/minimal/index.html +3 -3
package/cli/scaffold/ssr/app/app.js +18 -6
package/cli/scaffold/ssr/app/components/about.js +42 -15
package/cli/scaffold/ssr/app/components/blog/index.js +65 -0
package/cli/scaffold/ssr/app/components/blog/post.js +86 -0
package/cli/scaffold/ssr/app/routes.js +4 -2
package/cli/scaffold/ssr/global.css +117 -1
package/cli/scaffold/ssr/index.html +8 -2
package/cli/scaffold/ssr/server/data/posts.js +144 -0
package/cli/scaffold/ssr/server/index.js +117 -23
package/dist/zquery.dist.zip +0 -0
package/dist/zquery.js +85 -20
package/dist/zquery.min.js +2 -2
package/index.d.ts +5 -2
package/index.js +5 -4
package/package.json +1 -1
package/src/component.js +17 -2
package/src/router.js +61 -12
package/src/ssr.js +100 -0
package/tests/component.test.js +480 -0
package/tests/router.test.js +65 -1
package/tests/ssr.test.js +175 -0
package/tests/test-minifier.js +4 -4
package/types/misc.d.ts +23 -1
package/types/router.d.ts +25 -0
package/types/ssr.d.ts +33 -0

package/tests/ssr.test.js CHANGED Viewed

@@ -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/tests/test-minifier.js CHANGED Viewed

@@ -8,7 +8,7 @@ function minifyCSS(css) {
 }
 const tests = [
-  // Pseudo-classes with descendant combinator (the bug we fixed)
+  // Pseudo-classes with descendant combinator (the bug was that the space before :not() was being removed, which is incorrect)
   ['.docs-section :not(pre) > code { color: red }',     'space before :not()'],
   ['.foo :has(.bar) { color: red }',                     'space before :has()'],
   ['.foo :is(.a, .b) { color: red }',                    'space before :is()'],
@@ -18,12 +18,12 @@ const tests = [
   ['.foo::before { content: "x" }',                      '::before'],
   ['.foo ::after { content: "x" }',                      'space before ::after'],
-  // Pseudo-classes directly on element (no space — should stay compact)
+  // Pseudo-classes directly on element (no space - should stay compact)
   ['a:hover { color: red }',                             ':hover no space'],
   ['li:nth-child(2n + 1) { color: red }',                ':nth-child()'],
   ['input:focus-visible { outline: 1px }',               ':focus-visible'],
-  // calc() — spaces around operators are significant!
+  // calc() - spaces around operators are significant!
   ['.foo { width: calc(100% - 20px) }',                  'calc() spaces'],
   ['.foo { width: calc(50vw + 2rem) }',                  'calc() addition'],
   ['.foo { font-size: clamp(1rem, 2vw, 3rem) }',         'clamp()'],
@@ -145,7 +145,7 @@ assert('.bar :not(.a):not(.b) { color: red }',
 // Edge case: content with double spaces inside quotes
 const dblSpace = minifyCSS('.foo::before { content: "a  b" }');
 if (dblSpace.includes('content:"a b"')) {
-  console.log('WARN content double space — "a  b" collapsed to "a b" (cosmetic, not functional)');
+  console.log('WARN content double space - "a  b" collapsed to "a b" (cosmetic, not functional)');
 } else {
   console.log('PASS content double space preserved');
 }

package/types/misc.d.ts CHANGED Viewed

@@ -165,15 +165,37 @@ export function safeEval(expr: string, scope: object[]): any;
 /**
  * Supported event modifier strings for `@event` and `z-on:event` bindings.
  * Modifiers are appended to the event name with dots, e.g. `@click.prevent.stop`.
+ *
+ * **Key modifiers** — named shortcuts (`.enter`, `.escape`, `.tab`, `.space`,
+ * `.delete`, `.up`, `.down`, `.left`, `.right`) plus any arbitrary key matched
+ * case-insensitively against `KeyboardEvent.key` (e.g. `.a`, `.f1`, `.+`).
+ *
+ * **System modifiers** — `.ctrl`, `.shift`, `.alt`, `.meta` require the
+ * corresponding modifier key to be held.
  */
 export type EventModifier =
   | 'prevent'
   | 'stop'
   | 'self'
   | 'once'
+  | 'outside'
   | 'capture'
   | 'passive'
   | `debounce`
   | `debounce.${number}`
   | `throttle`
-  | `throttle.${number}`;
+  | `throttle.${number}`
+  | 'enter'
+  | 'escape'
+  | 'tab'
+  | 'space'
+  | 'delete'
+  | 'up'
+  | 'down'
+  | 'left'
+  | 'right'
+  | 'ctrl'
+  | 'shift'
+  | 'alt'
+  | 'meta'
+  | (string & {});

package/types/router.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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';