zero-query 0.6.3 → 0.8.6

package/types/http.d.ts

@@ -0,0 +1,81 @@
+/**
+ * HTTP Client — fetch-based wrapper with interceptors and auto-JSON.
+ *
+ * @module http
+ */
+
+/** The response object resolved by all HTTP request methods (except `raw`). */
+export interface HttpResponse<T = any> {
+  /** `true` if status 200-299. */
+  ok: boolean;
+  /** HTTP status code. */
+  status: number;
+  /** HTTP status text. */
+  statusText: string;
+  /** Response headers as a plain object. */
+  headers: Record<string, string>;
+  /** Auto-parsed body (JSON, text, or Blob depending on content type). */
+  data: T;
+  /** Raw `fetch` Response object. */
+  response: Response;
+}
+
+/** Per-request options passed to HTTP methods. */
+export interface HttpRequestOptions extends Omit<RequestInit, 'body' | 'method'> {
+  /** Additional headers (merged with defaults). */
+  headers?: Record<string, string>;
+  /** Override default timeout (ms). */
+  timeout?: number;
+  /** Abort signal for cancellation. */
+  signal?: AbortSignal;
+}
+
+/** Global HTTP configuration options. */
+export interface HttpConfigureOptions {
+  /** Prepended to non-absolute URLs. */
+  baseURL?: string;
+  /** Default headers (merged, not replaced). */
+  headers?: Record<string, string>;
+  /** Default timeout in ms (default 30 000). Set `0` to disable. */
+  timeout?: number;
+}
+
+/** Request interceptor function. */
+export type HttpRequestInterceptor = (
+  fetchOpts: RequestInit & { headers: Record<string, string> },
+  url: string,
+) => void | false | { url?: string; options?: RequestInit } | Promise<void | false | { url?: string; options?: RequestInit }>;
+
+/** Response interceptor function. */
+export type HttpResponseInterceptor = (result: HttpResponse) => void | Promise<void>;
+
+/** The `$.http` namespace. */
+export interface HttpClient {
+  /** GET request. `params` appended as query string. */
+  get<T = any>(url: string, params?: Record<string, any> | null, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
+  /** POST request. `data` sent as JSON body (or FormData). */
+  post<T = any>(url: string, data?: any, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
+  /** PUT request. */
+  put<T = any>(url: string, data?: any, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
+  /** PATCH request. */
+  patch<T = any>(url: string, data?: any, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
+  /** DELETE request. */
+  delete<T = any>(url: string, data?: any, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
+
+  /** Update default configuration for all subsequent requests. */
+  configure(options: HttpConfigureOptions): void;
+
+  /** Add a request interceptor (called before every request). */
+  onRequest(fn: HttpRequestInterceptor): void;
+
+  /** Add a response interceptor (called after every response, before error check). */
+  onResponse(fn: HttpResponseInterceptor): void;
+
+  /** Create a new `AbortController` for manual request cancellation. */
+  createAbort(): AbortController;
+
+  /** Direct passthrough to native `fetch()` — no JSON handling, no interceptors. */
+  raw(url: string, opts?: RequestInit): Promise<Response>;
+}
+
+export declare const http: HttpClient;

package/types/misc.d.ts

@@ -0,0 +1,179 @@
+/**
+ * DOM diffing, safe expression evaluator, and directive metadata.
+ *
+ * @module misc
+ */
+
+// ---------------------------------------------------------------------------
+// DOM Diffing (Morphing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Morph an existing DOM element's children to match new HTML.
+ * Only touches nodes that actually differ — preserves focus, scroll
+ * 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
+// ---------------------------------------------------------------------------
+
+/**
+ * CSP-safe expression evaluator. Parses and evaluates JS expressions
+ * without `eval()` or `new Function()`. Used internally by directives.
+ *
+ * @param expr  Expression string.
+ * @param scope Array of scope objects checked in order for identifier resolution.
+ * @returns Evaluation result, or `undefined` on error.
+ */
+export function safeEval(expr: string, scope: object[]): any;
+
+// ---------------------------------------------------------------------------
+// Directive System
+// ---------------------------------------------------------------------------
+//
+// Directives are special attributes processed by zQuery's component renderer.
+// They work in both `render()` template literals and external `templateUrl`
+// HTML files. All expressions evaluate in the component's state context
+// (bare names resolve to `this.state.*`; `props` and `refs` also available).
+//
+// ─── Structural Directives ──────────────────────────────────────────────
+//
+//   z-if="expression"          Conditional rendering — element removed when falsy.
+//   z-else-if="expression"     Else-if branch (must be immediate sibling of z-if).
+//   z-else                     Default branch (must follow z-if or z-else-if).
+//
+//   z-for="item in items"      List rendering — repeats the element per item.
+//     {{item.prop}}              Use double-brace interpolation for item data.
+//     (item, index) in items     Destructured index support.
+//     n in 5                     Number range → [1, 2, 3, 4, 5].
+//     (val, key) in object       Object iteration → {key, value} entries.
+//
+//   z-key="uniqueId"           Keyed reconciliation for list items.
+//                              Preserves DOM nodes across reorders. Use inside
+//                              z-for to give each item a stable identity.
+//                              Example: <li z-for="item in items" z-key="{{item.id}}">
+//
+//   z-show="expression"        Toggle `display: none` (element stays in DOM).
+//
+// ─── Attribute Directives ───────────────────────────────────────────────
+//
+//   z-bind:attr="expression"   Dynamic attribute binding.
+//   :attr="expression"         Shorthand for z-bind:attr.
+//                              false/null/undefined → removes the attribute.
+//                              true → sets empty attribute (e.g. disabled="").
+//
+//   z-class="expression"       Dynamic class binding.
+//                              String: space-separated class names.
+//                              Array: list of class names (falsy filtered).
+//                              Object: { className: condition } map.
+//
+//   z-style="expression"       Dynamic inline styles.
+//                              String: appended to existing cssText.
+//                              Object: { property: value } map (camelCase keys).
+//
+//   z-html="expression"        Set innerHTML from expression (use trusted content only).
+//   z-text="expression"        Set textContent from expression (safe, no HTML).
+//
+// ─── Form & Reference Directives ────────────────────────────────────────
+//
+//   z-model="stateKey"         Two-way binding for form elements.
+//     Supports: input, textarea, select, select[multiple], contenteditable.
+//     Nested keys: z-model="user.name" → this.state.user.name.
+//     Modifiers (boolean attributes on same element):
+//       z-lazy    — update on 'change' instead of 'input' (update on blur).
+//       z-trim    — auto .trim() whitespace before writing to state.
+//       z-number  — force Number() conversion regardless of input type.
+//
+//   z-ref="name"               Element reference → this.refs.name.
+//
+// ─── Event Directives ───────────────────────────────────────────────────
+//
+//   @event="method"            Event binding with delegation (shorthand).
+//   z-on:event="method"        Event binding with delegation (full syntax).
+//   @event="method(args)"      Pass arguments: strings, numbers, booleans,
+//                              null, $event, state.key references.
+//
+//   Event Modifiers (chainable with dots):
+//     .prevent                 event.preventDefault()
+//     .stop                    event.stopPropagation()
+//     .self                    Only fire if event.target === element itself.
+//     .once                    Handler fires at most once per element.
+//     .capture                 addEventListener with { capture: true }.
+//     .passive                 addEventListener with { passive: true }.
+//     .debounce.{ms}           Debounce: delay until {ms}ms idle (default 250).
+//     .throttle.{ms}           Throttle: invoke at most once per {ms}ms (default 250).
+//
+// ─── Special Directives ─────────────────────────────────────────────────
+//
+//   z-cloak                    Hidden until rendered (auto-removed after mount).
+//                              Global CSS: [z-cloak] { display: none !important }.
+//                              Also injects: *, *::before, *::after { -webkit-tap-highlight-color: transparent }.
+//
+//   z-pre                      Skip all directive processing for this element
+//                              and its descendants.
+//
+// ─── Slot System ────────────────────────────────────────────────────────
+//
+//   <slot>                     Default slot — replaced with child content
+//                              passed by the parent component.
+//   <slot name="header">       Named slot — replaced with child content that
+//                              has a matching slot="header" attribute.
+//   <slot>fallback</slot>      Fallback content shown when no slot content provided.
+//
+//   Parent usage:
+//     <my-component>
+//       <h1 slot="header">Title</h1>   (→ named slot "header")
+//       <p>Body text</p>               (→ default slot)
+//     </my-component>
+//
+// ─── Processing Order ───────────────────────────────────────────────────
+//
+//   1. z-for        (pre-innerHTML expansion)
+//   2. z-if chain   (DOM removal)
+//   3. z-show       (display toggle)
+//   4. z-bind / :   (dynamic attributes)
+//   5. z-class      (dynamic classes)
+//   6. z-style      (dynamic styles)
+//   7. z-html/text  (content injection)
+//   8. @/z-on       (event binding)
+//   9. z-ref        (element references)
+//  10. z-model      (two-way binding)
+//  11. z-cloak      (attribute removal)
+//
+// ---------------------------------------------------------------------------
+
+/**
+ * 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`.
+ */
+export type EventModifier =
+  | 'prevent'
+  | 'stop'
+  | 'self'
+  | 'once'
+  | 'capture'
+  | 'passive'
+  | `debounce`
+  | `debounce.${number}`
+  | `throttle`
+  | `throttle.${number}`;

package/types/reactive.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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;

package/types/router.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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. */
+  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;

package/types/ssr.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Server-Side Rendering — render components to HTML strings.
+ *
+ * @module ssr
+ */
+
+import type { ComponentDefinition } from './component';
+
+/** SSR application instance for server-side component rendering. */
+export interface SSRApp {
+  /** Register a component for SSR. */
+  component(name: string, definition: ComponentDefinition): SSRApp;
+
+  /**
+   * Render a component to an HTML string.
+   * @param componentName Registered component name.
+   * @param props Props to pass to the component.
+   * @param options Rendering options.
+   */
+  renderToString(
+    componentName: string,
+    props?: Record<string, any>,
+    options?: { hydrate?: boolean },
+  ): Promise<string>;
+
+  /**
+   * Render a full HTML page with a component mounted in a shell.
+   */
+  renderPage(options: {
+    component?: string;
+    props?: Record<string, any>;
+    title?: string;
+    styles?: string[];
+    scripts?: string[];
+    lang?: string;
+    meta?: string;
+    bodyAttrs?: string;
+  }): Promise<string>;
+}
+
+/** Create an SSR application instance. */
+export function createSSRApp(): SSRApp;
+
+/**
+ * Quick one-shot render of a component definition to an HTML string.
+ * @param definition Component definition object.
+ * @param props Props to pass.
+ */
+export function renderToString(definition: ComponentDefinition, props?: Record<string, any>): string;

package/types/store.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Store — reactive global state management.
+ *
+ * @module store
+ */
+
+import type { ReactiveProxy } from './reactive';
+
+/** Store configuration. */
+export interface StoreConfig<
+  S extends Record<string, any> = Record<string, any>,
+  A extends Record<string, (state: S, ...args: any[]) => any> = Record<string, (state: S, ...args: any[]) => any>,
+  G extends Record<string, (state: S) => any> = Record<string, (state: S) => any>,
+> {
+  /** Initial state. Function form creates a fresh copy. */
+  state?: S | (() => S);
+
+  /** Named action functions. The first argument is always the reactive `state`. */
+  actions?: A;
+
+  /** Computed getters derived from state (lazily evaluated). */
+  getters?: G;
+
+  /** Log dispatched actions to the console. */
+  debug?: boolean;
+}
+
+/** A store action history entry. */
+export interface StoreHistoryEntry {
+  action: string;
+  args: any[];
+  timestamp: number;
+}
+
+/** The reactive store instance. */
+export interface StoreInstance<
+  S extends Record<string, any> = Record<string, any>,
+  A extends Record<string, (state: S, ...args: any[]) => any> = Record<string, (state: S, ...args: any[]) => any>,
+  G extends Record<string, (state: S) => any> = Record<string, (state: S) => any>,
+> {
+  /** Reactive state proxy. Read / write triggers subscriptions. */
+  state: S & ReactiveProxy<S>;
+
+  /** Computed getters object. */
+  readonly getters: { readonly [K in keyof G]: ReturnType<G[K]> };
+
+  /** Log of all dispatched actions. */
+  readonly history: ReadonlyArray<StoreHistoryEntry>;
+
+  /**
+   * Execute a named action.
+   * @returns The action's return value.
+   */
+  dispatch<K extends keyof A>(
+    name: K,
+    ...args: A[K] extends (state: any, ...rest: infer P) => any ? P : any[]
+  ): ReturnType<A[K]>;
+  dispatch(name: string, ...args: any[]): any;
+
+  /**
+   * Subscribe to changes on a specific state key.
+   * Callback receives `(newValue, oldValue, key)`.
+   * @returns An unsubscribe function.
+   */
+  subscribe(key: string, fn: (value: any, oldValue: any, key: string) => void): () => void;
+
+  /**
+   * Subscribe to all state changes (wildcard).
+   * Callback receives `(key, newValue, oldValue)`.
+   * @returns An unsubscribe function.
+   */
+  subscribe(fn: (key: string, value: any, oldValue: any) => void): () => void;
+
+  /** Deep clone of the current state. */
+  snapshot(): S;
+
+  /** Replace the entire state. */
+  replaceState(newState: Partial<S>): void;
+
+  /**
+   * Add middleware. Return `false` from `fn` to block the action.
+   * Chainable.
+   */
+  use(fn: (actionName: string, args: any[], state: S) => boolean | void): StoreInstance<S, A, G>;
+
+  /** Replace state and clear action history. */
+  reset(initialState: Partial<S>): void;
+}
+
+/** Create a new global reactive store. */
+export function createStore<
+  S extends Record<string, any>,
+  A extends Record<string, (state: S, ...args: any[]) => any>,
+  G extends Record<string, (state: S) => any>,
+>(config: StoreConfig<S, A, G>): StoreInstance<S, A, G>;
+export function createStore<
+  S extends Record<string, any>,
+  A extends Record<string, (state: S, ...args: any[]) => any>,
+  G extends Record<string, (state: S) => any>,
+>(name: string, config: StoreConfig<S, A, G>): StoreInstance<S, A, G>;
+
+/** Retrieve a previously created store by name (default: `'default'`). */
+export function getStore<
+  S extends Record<string, any> = Record<string, any>,
+  A extends Record<string, (state: S, ...args: any[]) => any> = Record<string, (state: S, ...args: any[]) => any>,
+  G extends Record<string, (state: S) => any> = Record<string, (state: S) => any>,
+>(name?: string): StoreInstance<S, A, G> | null;