zero-query 0.7.5 → 0.8.6

package/tests/router.test.js

@@ -330,3 +330,320 @@ describe('Router — destroy', () => {
     expect(router._listeners.size).toBe(0);
   });
 });
+
+
+// ---------------------------------------------------------------------------
+// Wildcard / catch-all routes
+// ---------------------------------------------------------------------------
+
+describe('Router — wildcard routes', () => {
+  it('compiles wildcard route', () => {
+    const router = createRouter({
+      mode: 'hash',
+      routes: [
+        { path: '/docs/:section', component: 'docs-page' },
+        { path: '*', component: 'home-page' },
+      ],
+    });
+    // Wildcard is compiled as last route
+    expect(router._routes.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Query string handling
+// ---------------------------------------------------------------------------
+
+describe('Router — query parsing', () => {
+  it('_normalizePath strips query string for route matching', () => {
+    const router = createRouter({
+      mode: 'hash',
+      routes: [],
+    });
+    // _normalizePath does not strip query params — it only normalizes slashes and base prefix
+    const path = router._normalizePath('/docs?section=intro');
+    expect(path).toBe('/docs?section=intro');
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Multiple guards
+// ---------------------------------------------------------------------------
+
+describe('Router — multiple guards', () => {
+  it('registers multiple beforeEach guards', () => {
+    const router = createRouter({
+      mode: 'hash',
+      routes: [{ path: '/', component: 'home-page' }],
+    });
+    const g1 = vi.fn();
+    const g2 = vi.fn();
+    router.beforeEach(g1);
+    router.beforeEach(g2);
+    expect(router._guards.before.length).toBe(2);
+    expect(router._guards.before).toContain(g1);
+    expect(router._guards.before).toContain(g2);
+  });
+
+  it('registers multiple afterEach guards', () => {
+    const router = createRouter({
+      mode: 'hash',
+      routes: [{ path: '/', component: 'home-page' }],
+    });
+    const g1 = vi.fn();
+    const g2 = vi.fn();
+    router.afterEach(g1);
+    router.afterEach(g2);
+    expect(router._guards.after.length).toBe(2);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Route with multiple params
+// ---------------------------------------------------------------------------
+
+describe('Router — multi-param routes', () => {
+  it('compiles route with multiple params', () => {
+    const router = createRouter({
+      mode: 'hash',
+      routes: [
+        { path: '/post/:pid/comment/:cid', component: 'user-page' },
+      ],
+    });
+    const route = router._routes[0];
+    expect(route._regex.test('/post/1/comment/5')).toBe(true);
+    expect(route._keys).toEqual(['pid', 'cid']);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Same-path deduplication
+// ---------------------------------------------------------------------------
+
+describe('Router — same-path deduplication', () => {
+  let router;
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="app"></div>';
+    window.location.hash = '#/';
+    router = createRouter({
+      el: '#app',
+      mode: 'hash',
+      routes: [
+        { path: '/', component: 'home-page' },
+        { path: '/about', component: 'about-page' },
+      ],
+    });
+  });
+
+  it('skips duplicate hash navigation to the same path', () => {
+    router.navigate('/about');
+    expect(window.location.hash).toBe('#/about');
+    // Navigate to the same path again — should be a no-op
+    const result = router.navigate('/about');
+    expect(window.location.hash).toBe('#/about');
+    expect(result).toBe(router);                // still returns the router chain
+  });
+
+  it('allows forced duplicate navigation with options.force', () => {
+    router.navigate('/about');
+    // Force navigation to same path
+    router.navigate('/about', { force: true });
+    expect(window.location.hash).toBe('#/about');
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// History mode — same-path / hash-only navigation
+// ---------------------------------------------------------------------------
+
+describe('Router — history mode deduplication', () => {
+  let router;
+  let pushSpy, replaceSpy;
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="app"></div>';
+    pushSpy = vi.spyOn(window.history, 'pushState');
+    replaceSpy = vi.spyOn(window.history, 'replaceState');
+    router = createRouter({
+      el: '#app',
+      mode: 'history',
+      routes: [
+        { path: '/', component: 'home-page' },
+        { path: '/about', component: 'about-page' },
+        { path: '/docs', component: 'docs-page' },
+      ],
+    });
+    // Reset spy call counts after initial resolve
+    pushSpy.mockClear();
+    replaceSpy.mockClear();
+  });
+
+  afterEach(() => {
+    pushSpy.mockRestore();
+    replaceSpy.mockRestore();
+  });
+
+  it('uses pushState for different routes', () => {
+    router.navigate('/about');
+    expect(pushSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses replaceState for same-route hash-only change', () => {
+    // Navigate to /docs first
+    router.navigate('/docs');
+    pushSpy.mockClear();
+    replaceSpy.mockClear();
+    // Navigate to /docs#section — same route, different hash
+    router.navigate('/docs#section');
+    expect(pushSpy).not.toHaveBeenCalled();
+    expect(replaceSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Sub-route history substates
+// ---------------------------------------------------------------------------
+
+describe('Router — substates', () => {
+  let router;
+  let pushSpy;
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="app"></div>';
+    pushSpy = vi.spyOn(window.history, 'pushState');
+    router = createRouter({
+      el: '#app',
+      mode: 'history',
+      routes: [
+        { path: '/', component: 'home-page' },
+      ],
+    });
+    pushSpy.mockClear();
+  });
+
+  afterEach(() => {
+    pushSpy.mockRestore();
+  });
+
+  it('pushSubstate pushes a history entry with substate marker', () => {
+    router.pushSubstate('modal', { id: 'confirm' });
+    expect(pushSpy).toHaveBeenCalledTimes(1);
+    const state = pushSpy.mock.calls[0][0];
+    expect(state.__zq).toBe('substate');
+    expect(state.key).toBe('modal');
+    expect(state.data).toEqual({ id: 'confirm' });
+  });
+
+  it('onSubstate registers and unregisters listeners', () => {
+    const fn = vi.fn();
+    const unsub = router.onSubstate(fn);
+    expect(router._substateListeners).toContain(fn);
+    unsub();
+    expect(router._substateListeners).not.toContain(fn);
+  });
+
+  it('_fireSubstate calls listeners and returns true if any handles it', () => {
+    const fn1 = vi.fn(() => false);
+    const fn2 = vi.fn(() => true);
+    router.onSubstate(fn1);
+    router.onSubstate(fn2);
+    const handled = router._fireSubstate('modal', { id: 'x' }, 'pop');
+    expect(fn1).toHaveBeenCalledWith('modal', { id: 'x' }, 'pop');
+    expect(fn2).toHaveBeenCalledWith('modal', { id: 'x' }, 'pop');
+    expect(handled).toBe(true);
+  });
+
+  it('_fireSubstate returns false if no listener handles it', () => {
+    const fn = vi.fn(() => undefined);
+    router.onSubstate(fn);
+    const handled = router._fireSubstate('tab', { index: 0 }, 'pop');
+    expect(handled).toBe(false);
+  });
+
+  it('_fireSubstate catches errors in listeners', () => {
+    const fn = vi.fn(() => { throw new Error('oops'); });
+    router.onSubstate(fn);
+    // Should not throw
+    expect(() => router._fireSubstate('modal', {}, 'pop')).not.toThrow();
+  });
+
+  it('destroy clears substate listeners', () => {
+    router.onSubstate(() => {});
+    router.onSubstate(() => {});
+    router.destroy();
+    expect(router._substateListeners.length).toBe(0);
+  });
+
+  it('pushSubstate sets _inSubstate flag', () => {
+    expect(router._inSubstate).toBe(false);
+    router.pushSubstate('tab', { id: 'a' });
+    expect(router._inSubstate).toBe(true);
+  });
+
+  it('popstate past all substates fires reset action', () => {
+    const fn = vi.fn(() => true);
+    router.onSubstate(fn);
+    router.pushSubstate('tab', { id: 'a' });
+    expect(router._inSubstate).toBe(true);
+
+    // Simulate popstate landing on a non-substate entry
+    const evt = new PopStateEvent('popstate', { state: { __zq: 'route' } });
+    window.dispatchEvent(evt);
+
+    // Should have fired with reset action
+    expect(fn).toHaveBeenCalledWith(null, null, 'reset');
+    expect(router._inSubstate).toBe(false);
+  });
+
+  it('popstate on a substate entry keeps _inSubstate true', () => {
+    const fn = vi.fn(() => true);
+    router.onSubstate(fn);
+    router.pushSubstate('tab', { id: 'a' });
+    router.pushSubstate('tab', { id: 'b' });
+
+    // Simulate popstate landing on a substate entry
+    const evt = new PopStateEvent('popstate', {
+      state: { __zq: 'substate', key: 'tab', data: { id: 'a' } }
+    });
+    window.dispatchEvent(evt);
+
+    expect(fn).toHaveBeenCalledWith('tab', { id: 'a' }, 'pop');
+    expect(router._inSubstate).toBe(true);
+  });
+
+  it('reset action is not fired when no substates were active', () => {
+    const fn = vi.fn();
+    router.onSubstate(fn);
+    // _inSubstate is false, so popstate on a route entry should not fire reset
+    const evt = new PopStateEvent('popstate', { state: { __zq: 'route' } });
+    window.dispatchEvent(evt);
+    // fn should NOT have been called with 'reset'
+    const resetCalls = fn.mock.calls.filter(c => c[2] === 'reset');
+    expect(resetCalls.length).toBe(0);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+
+describe('Router — edge cases', () => {
+  it('handles empty routes array', () => {
+    const router = createRouter({ mode: 'hash', routes: [] });
+    expect(router._routes.length).toBe(0);
+  });
+
+  it('getRouter returns null before creation', () => {
+    // After the tests create routers, getRouter should return the latest
+    const r = getRouter();
+    expect(r).toBeDefined();
+  });
+});

package/tests/store.test.js

@@ -251,3 +251,129 @@ describe('Store — snapshot & replaceState', () => {
     expect(store.history.length).toBe(0);
   });
 });
+
+
+// ---------------------------------------------------------------------------
+// Multiple middleware
+// ---------------------------------------------------------------------------
+
+describe('Store — multiple middleware', () => {
+  it('runs middleware in order', () => {
+    const order = [];
+    const store = createStore('mw-multi', {
+      state: { x: 0 },
+      actions: { inc(state) { state.x++; } },
+    });
+    store.use(() => { order.push('a'); });
+    store.use(() => { order.push('b'); });
+    store.dispatch('inc');
+    expect(order).toEqual(['a', 'b']);
+  });
+
+  it('second middleware can block even if first passes', () => {
+    const store = createStore('mw-multi-block', {
+      state: { x: 0 },
+      actions: { inc(state) { state.x++; } },
+    });
+    store.use(() => true);
+    store.use(() => false);
+    store.dispatch('inc');
+    expect(store.state.x).toBe(0);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Async actions
+// ---------------------------------------------------------------------------
+
+describe('Store — async actions', () => {
+  it('supports async action returning promise', async () => {
+    const store = createStore('async-1', {
+      state: { data: null },
+      actions: {
+        async fetchData(state) {
+          state.data = await Promise.resolve('loaded');
+        },
+      },
+    });
+    await store.dispatch('fetchData');
+    expect(store.state.data).toBe('loaded');
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Subscriber deduplication
+// ---------------------------------------------------------------------------
+
+describe('Store — subscriber edge cases', () => {
+  it('same function subscribed twice fires twice', () => {
+    const store = createStore('sub-dedup', {
+      state: { x: 0 },
+      actions: { inc(state) { state.x++; } },
+    });
+    const fn = vi.fn();
+    store.subscribe('x', fn);
+    store.subscribe('x', fn); // Set deduplicates
+    store.dispatch('inc');
+    expect(fn).toHaveBeenCalledOnce(); // Set prevents duplicates
+  });
+
+  it('wildcard and key subscriber both fire', () => {
+    const store = createStore('sub-both', {
+      state: { x: 0 },
+      actions: { inc(state) { state.x++; } },
+    });
+    const keyFn = vi.fn();
+    const wildFn = vi.fn();
+    store.subscribe('x', keyFn);
+    store.subscribe(wildFn);
+    store.dispatch('inc');
+    expect(keyFn).toHaveBeenCalledOnce();
+    expect(wildFn).toHaveBeenCalledOnce();
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Action return value
+// ---------------------------------------------------------------------------
+
+describe('Store — action return value', () => {
+  it('dispatch returns action result', () => {
+    const store = createStore('ret-1', {
+      state: { x: 0 },
+      actions: { compute(state) { return state.x + 10; } },
+    });
+    expect(store.dispatch('compute')).toBe(10);
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Getters with multiple state keys
+// ---------------------------------------------------------------------------
+
+describe('Store — complex getters', () => {
+  it('getter uses multiple state keys', () => {
+    const store = createStore('getter-multi', {
+      state: { firstName: 'Tony', lastName: 'W' },
+      getters: {
+        fullName: (state) => `${state.firstName} ${state.lastName}`,
+      },
+    });
+    expect(store.getters.fullName).toBe('Tony W');
+  });
+
+  it('getter recalculates after state change', () => {
+    const store = createStore('getter-recalc', {
+      state: { count: 2 },
+      actions: { set(state, v) { state.count = v; } },
+      getters: { doubled: (s) => s.count * 2 },
+    });
+    expect(store.getters.doubled).toBe(4);
+    store.dispatch('set', 10);
+    expect(store.getters.doubled).toBe(20);
+  });
+});

package/tests/utils.test.js

@@ -1,9 +1,9 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
   debounce, throttle, pipe, once, sleep,
-  escapeHtml, trust, uuid, camelCase, kebabCase,
+  escapeHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,
-  bus,
+  storage, session, bus,
 } from '../src/utils.js';
 
 
@@ -298,6 +298,165 @@ describe('parseQuery', () => {
 });
 
 
+// ---------------------------------------------------------------------------
+// html template tag
+// ---------------------------------------------------------------------------
+
+describe('html template tag', () => {
+  it('auto-escapes interpolated values', () => {
+    const userInput = '<script>alert("xss")</script>';
+    const result = html`<div>${userInput}</div>`;
+    expect(result).toContain('&lt;script&gt;');
+    expect(result).not.toContain('<script>');
+  });
+
+  it('does not escape trusted HTML', () => {
+    const safe = trust('<b>bold</b>');
+    const result = html`<div>${safe}</div>`;
+    expect(result).toContain('<b>bold</b>');
+  });
+
+  it('handles null/undefined values', () => {
+    const result = html`<span>${null}</span>`;
+    expect(result).toBe('<span></span>');
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// storage helpers
+// ---------------------------------------------------------------------------
+
+describe('storage (localStorage wrapper)', () => {
+  beforeEach(() => { localStorage.clear(); });
+
+  it('set and get a value', () => {
+    storage.set('key', { a: 1 });
+    expect(storage.get('key')).toEqual({ a: 1 });
+  });
+
+  it('returns fallback for missing key', () => {
+    expect(storage.get('missing', 'default')).toBe('default');
+  });
+
+  it('returns null as default fallback', () => {
+    expect(storage.get('missing')).toBeNull();
+  });
+
+  it('remove deletes a key', () => {
+    storage.set('key', 42);
+    storage.remove('key');
+    expect(storage.get('key')).toBeNull();
+  });
+
+  it('clear removes all keys', () => {
+    storage.set('a', 1);
+    storage.set('b', 2);
+    storage.clear();
+    expect(storage.get('a')).toBeNull();
+    expect(storage.get('b')).toBeNull();
+  });
+
+  it('handles non-JSON values gracefully', () => {
+    localStorage.setItem('bad', '{not json}');
+    expect(storage.get('bad', 'fallback')).toBe('fallback');
+  });
+});
+
+
+describe('session (sessionStorage wrapper)', () => {
+  beforeEach(() => { sessionStorage.clear(); });
+
+  it('set and get a value', () => {
+    session.set('key', [1, 2, 3]);
+    expect(session.get('key')).toEqual([1, 2, 3]);
+  });
+
+  it('returns fallback for missing key', () => {
+    expect(session.get('missing', 'default')).toBe('default');
+  });
+
+  it('remove deletes a key', () => {
+    session.set('key', 'val');
+    session.remove('key');
+    expect(session.get('key')).toBeNull();
+  });
+
+  it('clear removes all keys', () => {
+    session.set('a', 1);
+    session.clear();
+    expect(session.get('a')).toBeNull();
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Event bus
+// ---------------------------------------------------------------------------
+
+describe('bus (event bus)', () => {
+  beforeEach(() => { bus.clear(); });
+
+  it('on() and emit()', () => {
+    const fn = vi.fn();
+    bus.on('test', fn);
+    bus.emit('test', 'data');
+    expect(fn).toHaveBeenCalledWith('data');
+  });
+
+  it('off() removes handler', () => {
+    const fn = vi.fn();
+    bus.on('test', fn);
+    bus.off('test', fn);
+    bus.emit('test');
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('on() returns unsubscribe function', () => {
+    const fn = vi.fn();
+    const unsub = bus.on('test', fn);
+    unsub();
+    bus.emit('test');
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('once() fires handler only once', () => {
+    const fn = vi.fn();
+    bus.once('test', fn);
+    bus.emit('test', 'first');
+    bus.emit('test', 'second');
+    expect(fn).toHaveBeenCalledOnce();
+    expect(fn).toHaveBeenCalledWith('first');
+  });
+
+  it('emit with multiple args', () => {
+    const fn = vi.fn();
+    bus.on('test', fn);
+    bus.emit('test', 1, 2, 3);
+    expect(fn).toHaveBeenCalledWith(1, 2, 3);
+  });
+
+  it('multiple handlers on same event', () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    bus.on('test', fn1);
+    bus.on('test', fn2);
+    bus.emit('test');
+    expect(fn1).toHaveBeenCalledOnce();
+    expect(fn2).toHaveBeenCalledOnce();
+  });
+
+  it('clear() removes all handlers', () => {
+    const fn = vi.fn();
+    bus.on('a', fn);
+    bus.on('b', fn);
+    bus.clear();
+    bus.emit('a');
+    bus.emit('b');
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Event bus
 // ---------------------------------------------------------------------------

package/types/collection.d.ts

@@ -209,9 +209,20 @@ export class ZQueryCollection {
 
   /** Get `innerHTML` of the first element, or `undefined` if empty. */
   html(): string | undefined;
-  /** Set `innerHTML` on all elements. */
+  /**
+   * Set content on all elements. Auto-morphs when the element already has
+   * children (preserves focus, scroll, form state, keyed reorder via LIS).
+   * Empty elements receive raw `innerHTML` for fast first-paint.
+   * Use `empty().html(content)` to force raw innerHTML.
+   */
   html(content: string): this;
 
+  /**
+   * Morph all elements' children to match new HTML using the diff engine.
+   * Always morphs regardless of whether the element already has children.
+   */
+  morph(content: string): this;
+
   /** Get `textContent` of the first element, or `undefined` if empty. */
   text(): string | undefined;
   /** Set `textContent` on all elements. */
@@ -248,7 +259,11 @@ export class ZQueryCollection {
   /** Clone elements (default: deep clone). */
   clone(deep?: boolean): ZQueryCollection;
 
-  /** Replace elements with new content. */
+  /**
+   * Replace elements with new content. When given an HTML string with the
+   * same tag name, morphs the element in place (preserving identity and state).
+   * Falls back to full replacement when the tag name differs or content is a Node.
+   */
   replaceWith(content: string | Node): this;
 
   /** Insert every element in the collection at the end of the target. */

package/types/component.d.ts

@@ -187,6 +187,13 @@ export function destroy(target: string | Element): void;
 /** Returns an object of all registered component definitions (for debugging). */
 export function getRegistry(): Record<string, ComponentDefinition>;
 
+/**
+ * Pre-load external templates and styles for a registered component.
+ * Useful for warming the cache before navigation to avoid blank flashes.
+ * @param name Registered component name.
+ */
+export function prefetch(name: string): Promise<void>;
+
 /** Handle returned by `$.style()`. */
 export interface StyleHandle {
   /** Remove all injected `<link>` elements. */

package/types/misc.d.ts

@@ -14,12 +14,25 @@
  * positions, video playback, and other live DOM state.
  *
  * Use `z-key="uniqueId"` attributes on list items for keyed reconciliation.
+ * Elements with `id`, `data-id`, or `data-key` attributes are auto-keyed.
  *
  * @param rootEl The live DOM container to patch.
  * @param newHTML The desired HTML string.
  */
 export function morph(rootEl: Element, newHTML: string): void;
 
+/**
+ * Morph a single element in place — diffs attributes and children
+ * without replacing the node reference. If the tag name matches, the
+ * element is patched in place (preserving identity). If the tag differs,
+ * the element is replaced.
+ *
+ * @param oldEl The live DOM element to patch.
+ * @param newHTML HTML string for the replacement element.
+ * @returns The resulting element (same ref if morphed, new if replaced).
+ */
+export function morphElement(oldEl: Element, newHTML: string): Element;
+
 // ---------------------------------------------------------------------------
 // Safe Expression Evaluator
 // ---------------------------------------------------------------------------