zero-query 1.1.1 → 1.2.0

package/types/reactive.d.ts

@@ -1,98 +1,98 @@
-/**
- * Reactive primitives - deep proxies and signals.
- *
- * @module reactive
- */
-
-/** Marker properties added to every reactive proxy. */
-export interface ReactiveProxy<T extends object = object> {
-  /** Always `true` - indicates this object is wrapped in a reactive Proxy. */
-  readonly __isReactive: true;
-  /** The original un-proxied object. */
-  readonly __raw: T;
-}
-
-/**
- * Wrap an object in a deep Proxy that fires `onChange` on every set / delete.
- *
- * @param target   Plain object to make reactive.
- * @param onChange  Called with `(key, newValue, oldValue)` on every mutation.
- * @returns A proxied version of `target` with `__isReactive` and `__raw` markers.
- */
-export function reactive<T extends object>(
-  target: T,
-  onChange: (key: string, value: any, oldValue: any) => void,
-): T & ReactiveProxy<T>;
-
-/**
- * A lightweight reactive primitive (inspired by Solid / Preact signals).
- *
- * Reading `.value` inside an `effect()` auto-subscribes to changes.
- * Writing `.value` triggers all subscribers and dependent effects.
- */
-export class Signal<T = any> {
-  constructor(value: T);
-
-  /**
-   * Get or set the current value.
-   * The getter automatically tracks dependencies when accessed inside an `effect()`.
-   */
-  value: T;
-
-  /** Read the current value *without* creating a subscription (no tracking). */
-  peek(): T;
-
-  /**
-   * Manually subscribe to changes.
-   * @returns An unsubscribe function.
-   */
-  subscribe(fn: () => void): () => void;
-
-  toString(): string;
-}
-
-/** Create a new `Signal`. */
-export function signal<T>(initial: T): Signal<T>;
-
-/**
- * Create a derived signal that recomputes when its dependencies change.
- * The returned signal is effectively read-only.
- */
-export function computed<T>(fn: () => T): Signal<T>;
-
-/**
- * Create a side-effect that auto-subscribes to signals read during execution.
- * Re-runs automatically when any tracked signal changes.
- *
- * @param fn The effect function. Executed immediately on creation, then on signal changes.
- * @returns A dispose function - calling it stops tracking and prevents re-runs.
- *
- * @example
- * const count = signal(0);
- * const stop = effect(() => console.log(count.value)); // logs 0
- * count.value = 1; // logs 1
- * stop();          // effect no longer runs
- */
-export function effect(fn: () => void): () => void;
-
-/**
- * Batch multiple signal writes - subscribers and effects fire once at the end.
- * Nested batches are merged into the outermost one.
- *
- * @example
- * const a = signal(0);
- * const b = signal(0);
- * batch(() => {
- *   a.value = 1;
- *   b.value = 2;
- * }); // effects run once with both values updated
- */
-export function batch<R = void>(fn: () => R): R;
-
-/**
- * Execute a function without tracking signal reads as dependencies.
- * Useful inside effects when you need to read a signal without subscribing.
- *
- * @returns The return value of `fn`.
- */
-export function untracked<T>(fn: () => T): T;
+/**
+ * Reactive primitives - deep proxies and signals.
+ *
+ * @module reactive
+ */
+
+/** Marker properties added to every reactive proxy. */
+export interface ReactiveProxy<T extends object = object> {
+  /** Always `true` - indicates this object is wrapped in a reactive Proxy. */
+  readonly __isReactive: true;
+  /** The original un-proxied object. */
+  readonly __raw: T;
+}
+
+/**
+ * Wrap an object in a deep Proxy that fires `onChange` on every set / delete.
+ *
+ * @param target   Plain object to make reactive.
+ * @param onChange  Called with `(key, newValue, oldValue)` on every mutation.
+ * @returns A proxied version of `target` with `__isReactive` and `__raw` markers.
+ */
+export function reactive<T extends object>(
+  target: T,
+  onChange: (key: string, value: any, oldValue: any) => void,
+): T & ReactiveProxy<T>;
+
+/**
+ * A lightweight reactive primitive (inspired by Solid / Preact signals).
+ *
+ * Reading `.value` inside an `effect()` auto-subscribes to changes.
+ * Writing `.value` triggers all subscribers and dependent effects.
+ */
+export class Signal<T = any> {
+  constructor(value: T);
+
+  /**
+   * Get or set the current value.
+   * The getter automatically tracks dependencies when accessed inside an `effect()`.
+   */
+  value: T;
+
+  /** Read the current value *without* creating a subscription (no tracking). */
+  peek(): T;
+
+  /**
+   * Manually subscribe to changes.
+   * @returns An unsubscribe function.
+   */
+  subscribe(fn: () => void): () => void;
+
+  toString(): string;
+}
+
+/** Create a new `Signal`. */
+export function signal<T>(initial: T): Signal<T>;
+
+/**
+ * Create a derived signal that recomputes when its dependencies change.
+ * The returned signal is effectively read-only.
+ */
+export function computed<T>(fn: () => T): Signal<T>;
+
+/**
+ * Create a side-effect that auto-subscribes to signals read during execution.
+ * Re-runs automatically when any tracked signal changes.
+ *
+ * @param fn The effect function. Executed immediately on creation, then on signal changes.
+ * @returns A dispose function - calling it stops tracking and prevents re-runs.
+ *
+ * @example
+ * const count = signal(0);
+ * const stop = effect(() => console.log(count.value)); // logs 0
+ * count.value = 1; // logs 1
+ * stop();          // effect no longer runs
+ */
+export function effect(fn: () => void): () => void;
+
+/**
+ * Batch multiple signal writes - subscribers and effects fire once at the end.
+ * Nested batches are merged into the outermost one.
+ *
+ * @example
+ * const a = signal(0);
+ * const b = signal(0);
+ * batch(() => {
+ *   a.value = 1;
+ *   b.value = 2;
+ * }); // effects run once with both values updated
+ */
+export function batch<R = void>(fn: () => R): R;
+
+/**
+ * Execute a function without tracking signal reads as dependencies.
+ * Useful inside effects when you need to read a signal without subscribing.
+ *
+ * @returns The return value of `fn`.
+ */
+export function untracked<T>(fn: () => T): T;

package/types/router.d.ts

@@ -1,190 +1,190 @@
-/**
- * SPA Router - history and hash-based client-side routing.
- *
- * @module router
- */
-
-/** A single route definition. */
-export interface RouteDefinition {
-  /**
-   * URL pattern. Supports `:param` segments and `*` wildcard.
-   * @example '/user/:id'
-   */
-  path: string;
-
-  /** Registered component name (auto-mounted), or a render function. */
-  component: string | ((route: NavigationContext) => string);
-
-  /** Async function called before mounting (for lazy-loading modules). */
-  load?: () => Promise<any>;
-
-  /**
-   * An additional path that also matches this route.
-   * Missing `:param` values will be `undefined`.
-   */
-  fallback?: string;
-}
-
-/** Navigation context passed to guards and `onChange` listeners. */
-export interface NavigationContext {
-  /** The matched route definition. */
-  route: RouteDefinition;
-  /** Parsed `:param` values. */
-  params: Record<string, string>;
-  /** Parsed query-string values. */
-  query: Record<string, string>;
-  /** Matched path (base-stripped in history mode). */
-  path: string;
-}
-
-/** Router configuration. */
-export interface RouterConfig {
-  /**
-   * Outlet element where route components are rendered.
-   * If omitted, the router auto-detects a `<z-outlet>` element in the DOM.
-   * Acts as an explicit override of the default `<z-outlet>` lookup.
-   */
-  el?: string | Element;
-  /** Routing mode (default: `'history'`; `'hash'` for file:// or hash routing). */
-  mode?: 'history' | 'hash';
-  /**
-   * Base path prefix (e.g. `'/my-app'`).
-   * Auto-detected from `<base href>` or `window.__ZQ_BASE` if not set.
-   */
-  base?: string;
-  /** Route definitions. */
-  routes?: RouteDefinition[];
-  /** Component name to render when no route matches (404). */
-  fallback?: string;
-}
-
-/** The SPA router instance. */
-export interface RouterInstance {
-  /**
-   * Push a new state and resolve the route.
-   * Supports `:param` interpolation when `options.params` is provided.
-   * Same-path navigation is deduplicated (skipped unless `options.force` is true).
-   * Hash-only changes on the same route use `replaceState` to avoid extra history entries.
-   * @example
-   * router.navigate('/user/:id', { params: { id: 42 } }); // navigates to /user/42
-   * router.navigate('/dashboard', { state: { from: 'login' } });
-   */
-  navigate(path: string, options?: { params?: Record<string, string | number>; state?: any; force?: boolean }): RouterInstance;
-  /**
-   * Replace the current state (no new history entry).
-   * Supports `:param` interpolation when `options.params` is provided.
-   * @example
-   * router.replace('/user/:id', { params: { id: 42 } }); // replaces with /user/42
-   */
-  replace(path: string, options?: { params?: Record<string, string | number>; state?: any }): RouterInstance;
-  /** `history.back()` */
-  back(): RouterInstance;
-  /** `history.forward()` */
-  forward(): RouterInstance;
-  /** `history.go(n)` */
-  go(n: number): RouterInstance;
-
-  /** Add a route dynamically. Chainable. */
-  add(route: RouteDefinition): RouterInstance;
-  /** Remove a route by path. */
-  remove(path: string): RouterInstance;
-
-  /**
-   * Navigation guard - runs before each route change.
-   * Return `false` to cancel, or a `string` to redirect.
-   */
-  beforeEach(
-    fn: (
-      to: NavigationContext,
-      from: NavigationContext | null,
-    ) => boolean | string | void | Promise<boolean | string | void>,
-  ): RouterInstance;
-
-  /** Post-navigation hook. */
-  afterEach(
-    fn: (to: NavigationContext, from: NavigationContext | null) => void | Promise<void>,
-  ): RouterInstance;
-
-  /**
-   * Subscribe to route changes.
-   * @returns An unsubscribe function.
-   */
-  onChange(
-    fn: (to: NavigationContext, from: NavigationContext | null) => void,
-  ): () => void;
-
-  /**
-   * Push a lightweight history entry for in-component UI state (modal, tab, panel).
-   * The URL does NOT change - only a history entry is added so the back button
-   * can undo the UI change before navigating away from the route.
-   * @param key - identifier for the substate (e.g. 'modal', 'tab')
-   * @param data - arbitrary serializable state
-   * @example
-   * router.pushSubstate('modal', { id: 'confirm-delete' });
-   */
-  pushSubstate(key: string, data?: any): RouterInstance;
-
-  /**
-   * Register a listener for substate pops (back button on a substate entry).
-   * The callback receives `(key, data, action)` and should return `true` if it
-   * handled the pop (prevents route resolution). If no listener returns `true`,
-   * normal route resolution proceeds.
-   * @returns An unsubscribe function.
-   * @example
-   * const unsub = router.onSubstate((key, data, action) => {
-   *   if (action === 'reset') { resetDefaults(); return true; }
-   *   if (key === 'modal') { closeModal(); return true; }
-   * });
-   */
-  onSubstate(
-    fn: (key: string | null, data: any, action: 'pop' | 'resolve' | 'reset') => boolean | void,
-  ): () => void;
-
-  /** Teardown the router and mounted component. */
-  destroy(): void;
-
-  /** Resolve a path applying the base prefix. */
-  resolve(path: string): string;
-
-  // -- Properties ----------------------------------------------------------
-
-  /** Current navigation context. */
-  readonly current: NavigationContext | null;
-  /** Current path (base-stripped in history mode). */
-  readonly path: string;
-  /** Parsed query-string object. */
-  readonly query: Record<string, string>;
-  /** Configured base path. */
-  readonly base: string;
-}
-
-/** Create and activate a client-side SPA router. */
-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;
+/**
+ * SPA Router - history and hash-based client-side routing.
+ *
+ * @module router
+ */
+
+/** A single route definition. */
+export interface RouteDefinition {
+  /**
+   * URL pattern. Supports `:param` segments and `*` wildcard.
+   * @example '/user/:id'
+   */
+  path: string;
+
+  /** Registered component name (auto-mounted), or a render function. */
+  component: string | ((route: NavigationContext) => string);
+
+  /** Async function called before mounting (for lazy-loading modules). */
+  load?: () => Promise<any>;
+
+  /**
+   * An additional path that also matches this route.
+   * Missing `:param` values will be `undefined`.
+   */
+  fallback?: string;
+}
+
+/** Navigation context passed to guards and `onChange` listeners. */
+export interface NavigationContext {
+  /** The matched route definition. */
+  route: RouteDefinition;
+  /** Parsed `:param` values. */
+  params: Record<string, string>;
+  /** Parsed query-string values. */
+  query: Record<string, string>;
+  /** Matched path (base-stripped in history mode). */
+  path: string;
+}
+
+/** Router configuration. */
+export interface RouterConfig {
+  /**
+   * Outlet element where route components are rendered.
+   * If omitted, the router auto-detects a `<z-outlet>` element in the DOM.
+   * Acts as an explicit override of the default `<z-outlet>` lookup.
+   */
+  el?: string | Element;
+  /** Routing mode (default: `'history'`; `'hash'` for file:// or hash routing). */
+  mode?: 'history' | 'hash';
+  /**
+   * Base path prefix (e.g. `'/my-app'`).
+   * Auto-detected from `<base href>` or `window.__ZQ_BASE` if not set.
+   */
+  base?: string;
+  /** Route definitions. */
+  routes?: RouteDefinition[];
+  /** Component name to render when no route matches (404). */
+  fallback?: string;
+}
+
+/** The SPA router instance. */
+export interface RouterInstance {
+  /**
+   * Push a new state and resolve the route.
+   * Supports `:param` interpolation when `options.params` is provided.
+   * Same-path navigation is deduplicated (skipped unless `options.force` is true).
+   * Hash-only changes on the same route use `replaceState` to avoid extra history entries.
+   * @example
+   * router.navigate('/user/:id', { params: { id: 42 } }); // navigates to /user/42
+   * router.navigate('/dashboard', { state: { from: 'login' } });
+   */
+  navigate(path: string, options?: { params?: Record<string, string | number>; state?: any; force?: boolean }): RouterInstance;
+  /**
+   * Replace the current state (no new history entry).
+   * Supports `:param` interpolation when `options.params` is provided.
+   * @example
+   * router.replace('/user/:id', { params: { id: 42 } }); // replaces with /user/42
+   */
+  replace(path: string, options?: { params?: Record<string, string | number>; state?: any }): RouterInstance;
+  /** `history.back()` */
+  back(): RouterInstance;
+  /** `history.forward()` */
+  forward(): RouterInstance;
+  /** `history.go(n)` */
+  go(n: number): RouterInstance;
+
+  /** Add a route dynamically. Chainable. */
+  add(route: RouteDefinition): RouterInstance;
+  /** Remove a route by path. */
+  remove(path: string): RouterInstance;
+
+  /**
+   * Navigation guard - runs before each route change.
+   * Return `false` to cancel, or a `string` to redirect.
+   */
+  beforeEach(
+    fn: (
+      to: NavigationContext,
+      from: NavigationContext | null,
+    ) => boolean | string | void | Promise<boolean | string | void>,
+  ): RouterInstance;
+
+  /** Post-navigation hook. */
+  afterEach(
+    fn: (to: NavigationContext, from: NavigationContext | null) => void | Promise<void>,
+  ): RouterInstance;
+
+  /**
+   * Subscribe to route changes.
+   * @returns An unsubscribe function.
+   */
+  onChange(
+    fn: (to: NavigationContext, from: NavigationContext | null) => void,
+  ): () => void;
+
+  /**
+   * Push a lightweight history entry for in-component UI state (modal, tab, panel).
+   * The URL does NOT change - only a history entry is added so the back button
+   * can undo the UI change before navigating away from the route.
+   * @param key - identifier for the substate (e.g. 'modal', 'tab')
+   * @param data - arbitrary serializable state
+   * @example
+   * router.pushSubstate('modal', { id: 'confirm-delete' });
+   */
+  pushSubstate(key: string, data?: any): RouterInstance;
+
+  /**
+   * Register a listener for substate pops (back button on a substate entry).
+   * The callback receives `(key, data, action)` and should return `true` if it
+   * handled the pop (prevents route resolution). If no listener returns `true`,
+   * normal route resolution proceeds.
+   * @returns An unsubscribe function.
+   * @example
+   * const unsub = router.onSubstate((key, data, action) => {
+   *   if (action === 'reset') { resetDefaults(); return true; }
+   *   if (key === 'modal') { closeModal(); return true; }
+   * });
+   */
+  onSubstate(
+    fn: (key: string | null, data: any, action: 'pop' | 'resolve' | 'reset') => boolean | void,
+  ): () => void;
+
+  /** Teardown the router and mounted component. */
+  destroy(): void;
+
+  /** Resolve a path applying the base prefix. */
+  resolve(path: string): string;
+
+  // -- Properties ----------------------------------------------------------
+
+  /** Current navigation context. */
+  readonly current: NavigationContext | null;
+  /** Current path (base-stripped in history mode). */
+  readonly path: string;
+  /** Parsed query-string object. */
+  readonly query: Record<string, string>;
+  /** Configured base path. */
+  readonly base: string;
+}
+
+/** Create and activate a client-side SPA router. */
+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;