zero-query 0.6.3 → 0.7.5

package/types/collection.d.ts

@@ -0,0 +1,368 @@
+/**
+ * ZQueryCollection — chainable DOM element wrapper.
+ *
+ * Returned by `$()`, `$.all()`, `$.create()`, and many traversal methods.
+ * Similar to a jQuery object: wraps an array of elements with fluent methods.
+ *
+ * @module collection
+ */
+
+/**
+ * Chainable wrapper around an array of DOM elements, similar to a jQuery object.
+ * Returned by `$.all()` and many traversal / filtering methods.
+ */
+export class ZQueryCollection {
+  /** Number of elements in the collection. */
+  readonly length: number;
+
+  /** Access element by numeric index. */
+  readonly [index: number]: Element;
+
+  constructor(elements: Element | Element[]);
+
+  // -- Iteration -----------------------------------------------------------
+
+  /**
+   * Iterate over each element. `this` inside the callback is the element.
+   * @returns The collection (for chaining).
+   */
+  each(fn: (this: Element, index: number, element: Element) => void): this;
+
+  /**
+   * Map over elements and return a plain array.
+   */
+  map<T>(fn: (this: Element, index: number, element: Element) => T): T[];
+
+  /**
+   * Iterate elements with Array-style `forEach`. Returns `this` for chaining.
+   */
+  forEach(fn: (element: Element, index: number, elements: Element[]) => void): this;
+
+  /** First raw element, or `null`. */
+  first(): Element | null;
+
+  /** Last raw element, or `null`. */
+  last(): Element | null;
+
+  /** New collection containing only the element at `index`. */
+  eq(index: number): ZQueryCollection;
+
+  /** Convert to a plain `Element[]`. */
+  toArray(): Element[];
+
+  /** Iterable protocol — works with `for...of` and spread. */
+  [Symbol.iterator](): IterableIterator<Element>;
+
+  // -- Traversal -----------------------------------------------------------
+
+  /** Descendants matching `selector`. */
+  find(selector: string): ZQueryCollection;
+
+  /** Unique parent elements. */
+  parent(): ZQueryCollection;
+
+  /** Nearest ancestor matching `selector`. */
+  closest(selector: string): ZQueryCollection;
+
+  /** Direct children, optionally filtered by `selector`. */
+  children(selector?: string): ZQueryCollection;
+
+  /** All sibling elements. */
+  siblings(): ZQueryCollection;
+
+  /** Next sibling of each element, optionally filtered by selector. */
+  next(selector?: string): ZQueryCollection;
+
+  /** Previous sibling of each element, optionally filtered by selector. */
+  prev(selector?: string): ZQueryCollection;
+
+  /** All following siblings, optionally filtered by selector. */
+  nextAll(selector?: string): ZQueryCollection;
+
+  /** Following siblings up to (but not including) the element matching `selector`. */
+  nextUntil(selector?: string, filter?: string): ZQueryCollection;
+
+  /** All preceding siblings, optionally filtered by selector. */
+  prevAll(selector?: string): ZQueryCollection;
+
+  /** Preceding siblings up to (but not including) the element matching `selector`. */
+  prevUntil(selector?: string, filter?: string): ZQueryCollection;
+
+  /** All ancestor elements, optionally filtered by selector (deduplicated). */
+  parents(selector?: string): ZQueryCollection;
+
+  /** Ancestors up to (but not including) the element matching `selector`. */
+  parentsUntil(selector?: string, filter?: string): ZQueryCollection;
+
+  /** All child nodes including text and comment nodes. */
+  contents(): ZQueryCollection;
+
+  // -- Filtering -----------------------------------------------------------
+
+  /** Keep elements matching a CSS selector or predicate. */
+  filter(selector: string): ZQueryCollection;
+  filter(fn: (element: Element, index: number) => boolean): ZQueryCollection;
+
+  /** Remove elements matching a CSS selector or predicate. */
+  not(selector: string): ZQueryCollection;
+  not(fn: (this: Element, index: number, element: Element) => boolean): ZQueryCollection;
+
+  /** Keep elements that have a descendant matching `selector`. */
+  has(selector: string): ZQueryCollection;
+
+  /** Check if any element matches the selector or predicate. */
+  is(selector: string): boolean;
+  is(fn: (this: Element, index: number, element: Element) => boolean): boolean;
+
+  /** Return a subset of the collection. */
+  slice(start: number, end?: number): ZQueryCollection;
+
+  /** Add elements to the collection, returning a new combined collection. */
+  add(selector: string, context?: Element | Document): ZQueryCollection;
+  add(element: Element): ZQueryCollection;
+  add(collection: ZQueryCollection): ZQueryCollection;
+
+  /** Retrieve a raw DOM element by index (supports negative). No args → array of all elements. */
+  get(): Element[];
+  get(index: number): Element | undefined;
+
+  /** Position of the first element among its siblings, or index of a given element/selector in the collection. */
+  index(selector?: string | Element): number;
+
+  // -- Classes -------------------------------------------------------------
+
+  /** Add one or more classes (space-separated strings accepted). */
+  addClass(...names: string[]): this;
+
+  /** Remove one or more classes. */
+  removeClass(...names: string[]): this;
+
+  /** Toggle one or more classes (space-separated strings accepted). Optional trailing `force` boolean. */
+  toggleClass(...names: Array<string | boolean>): this;
+
+  /** Check whether the first element has the given class. */
+  hasClass(name: string): boolean;
+
+  // -- Attributes & Properties ---------------------------------------------
+
+  /** Get attribute value of the first element. */
+  attr(name: string): string | null;
+  /** Set attribute on all elements. */
+  attr(name: string, value: string): this;
+
+  /** Remove attribute from all elements. */
+  removeAttr(name: string): this;
+
+  /** Get JS property of the first element. */
+  prop(name: string): any;
+  /** Set JS property on all elements. */
+  prop(name: string, value: any): this;
+
+  /** Get data attribute value (JSON auto-parsed). No key → full dataset. */
+  data(): DOMStringMap;
+  data(key: string): any;
+  /** Set data attribute on all elements. Objects are JSON-stringified. */
+  data(key: string, value: any): this;
+
+  // -- CSS & Dimensions ----------------------------------------------------
+
+  /** Get computed style property of the first element, or `undefined` if empty. */
+  css(property: string): string | undefined;
+  /** Set inline styles on all elements. */
+  css(props: Partial<CSSStyleDeclaration>): this;
+
+  /** First element's width (from `getBoundingClientRect`). */
+  width(): number | undefined;
+
+  /** First element's height. */
+  height(): number | undefined;
+
+  /** Position relative to the document. */
+  offset(): { top: number; left: number; width: number; height: number } | null;
+
+  /** Position relative to the offset parent. */
+  position(): { top: number; left: number } | null;
+
+  /** Get vertical scroll position of the first element. */
+  scrollTop(): number | undefined;
+  /** Set vertical scroll position on all elements. */
+  scrollTop(value: number): this;
+
+  /** Get horizontal scroll position of the first element. */
+  scrollLeft(): number | undefined;
+  /** Set horizontal scroll position on all elements. */
+  scrollLeft(value: number): this;
+
+  /** Width including padding (clientWidth). */
+  innerWidth(): number | undefined;
+
+  /** Height including padding (clientHeight). */
+  innerHeight(): number | undefined;
+
+  /** Width including padding + border. Pass `true` to include margin. */
+  outerWidth(includeMargin?: boolean): number | undefined;
+
+  /** Height including padding + border. Pass `true` to include margin. */
+  outerHeight(includeMargin?: boolean): number | undefined;
+
+  // -- Content -------------------------------------------------------------
+
+  /** Get `innerHTML` of the first element, or `undefined` if empty. */
+  html(): string | undefined;
+  /** Set `innerHTML` on all elements. */
+  html(content: string): this;
+
+  /** Get `textContent` of the first element, or `undefined` if empty. */
+  text(): string | undefined;
+  /** Set `textContent` on all elements. */
+  text(content: string): this;
+
+  /** Get value of the first input/select/textarea, or `undefined` if empty. */
+  val(): string | undefined;
+  /** Set value on all inputs. */
+  val(value: string): this;
+
+  // -- DOM Manipulation ----------------------------------------------------
+
+  /** Insert content at the end of each element. */
+  append(content: string | Node | ZQueryCollection): this;
+
+  /** Insert content at the beginning of each element. */
+  prepend(content: string | Node): this;
+
+  /** Insert content after each element. */
+  after(content: string | Node): this;
+
+  /** Insert content before each element. */
+  before(content: string | Node): this;
+
+  /** Wrap each element with the given HTML string or Node. */
+  wrap(wrapper: string | Node): this;
+
+  /** Remove all elements from the DOM. */
+  remove(): this;
+
+  /** Clear `innerHTML` of all elements. */
+  empty(): this;
+
+  /** Clone elements (default: deep clone). */
+  clone(deep?: boolean): ZQueryCollection;
+
+  /** Replace elements with new content. */
+  replaceWith(content: string | Node): this;
+
+  /** Insert every element in the collection at the end of the target. */
+  appendTo(target: string | Element | ZQueryCollection): this;
+
+  /** Insert every element in the collection at the beginning of the target. */
+  prependTo(target: string | Element | ZQueryCollection): this;
+
+  /** Insert every element in the collection after the target. */
+  insertAfter(target: string | Element | ZQueryCollection): this;
+
+  /** Insert every element in the collection before the target. */
+  insertBefore(target: string | Element | ZQueryCollection): this;
+
+  /** Replace the target elements with the collection's elements. */
+  replaceAll(target: string | Element | ZQueryCollection): this;
+
+  /** Remove the parent of each element, optionally only if it matches `selector`. */
+  unwrap(selector?: string): this;
+
+  /** Wrap all elements together in a single wrapper. */
+  wrapAll(wrapper: string | Element): this;
+
+  /** Wrap the inner contents of each element with the given wrapper. */
+  wrapInner(wrapper: string | Element): this;
+
+  /** Remove all elements from the DOM (alias for `remove`). */
+  detach(): this;
+
+  // -- Visibility ----------------------------------------------------------
+
+  /** Show elements. Optional display value (default: `''`). */
+  show(display?: string): this;
+
+  /** Set `display: none` on all elements. */
+  hide(): this;
+
+  /** Toggle visibility. */
+  toggle(display?: string): this;
+
+  // -- Events --------------------------------------------------------------
+
+  /** Attach event handler. Space-separated events accepted. */
+  on(events: string, handler: (event: Event) => void): this;
+  /** Delegated event handler. */
+  on(events: string, selector: string, handler: (this: Element, event: Event) => void): this;
+
+  /** Remove event handler. */
+  off(events: string, handler: (event: Event) => void): this;
+
+  /** One-time event handler. */
+  one(event: string, handler: (event: Event) => void): this;
+
+  /**
+   * Dispatch a `CustomEvent` with optional detail payload.
+   * Bubbles by default.
+   */
+  trigger(event: string, detail?: any): this;
+
+  /** Attach click handler, or trigger a click when called with no arguments. */
+  click(fn?: (event: Event) => void): this;
+
+  /** Attach submit handler, or trigger submit when called with no arguments. */
+  submit(fn?: (event: Event) => void): this;
+
+  /** Focus the first element. */
+  focus(): this;
+
+  /** Blur the first element. */
+  blur(): this;
+
+  /** Bind mouseenter and mouseleave handlers. If only one function is provided, it's used for both. */
+  hover(enterFn: (event: Event) => void, leaveFn?: (event: Event) => void): this;
+
+  // -- Animation -----------------------------------------------------------
+
+  /**
+   * CSS transition animation.
+   * @param props   CSS properties to animate to.
+   * @param duration Duration in ms (default 300).
+   * @param easing  CSS easing function (default `'ease'`).
+   */
+  animate(
+    props: Partial<CSSStyleDeclaration>,
+    duration?: number,
+    easing?: string,
+  ): Promise<ZQueryCollection>;
+
+  /** Fade in (opacity 0→1). Default 300 ms. */
+  fadeIn(duration?: number): Promise<ZQueryCollection>;
+
+  /** Fade out (opacity 1→0) then hide. Default 300 ms. */
+  fadeOut(duration?: number): Promise<ZQueryCollection>;
+
+  /** Toggle fade in/out. Default 300 ms. */
+  fadeToggle(duration?: number): Promise<ZQueryCollection>;
+
+  /** Fade to a specific opacity. */
+  fadeTo(duration: number, opacity: number): Promise<ZQueryCollection>;
+
+  /** Slide down (reveal). Default 300 ms. */
+  slideDown(duration?: number): this;
+
+  /** Slide up (hide). Default 300 ms. */
+  slideUp(duration?: number): this;
+
+  /** Toggle height with a slide animation. Default 300 ms. */
+  slideToggle(duration?: number): this;
+
+  // -- Form Helpers --------------------------------------------------------
+
+  /** URL-encoded form data string. */
+  serialize(): string;
+
+  /** Form data as key/value object. Duplicate keys become arrays. */
+  serializeObject(): Record<string, string | string[]>;
+}

package/types/component.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Component system — define, mount, and manage reactive components.
+ *
+ * @module component
+ */
+
+import type { ReactiveProxy } from './reactive';
+import type { NavigationContext } from './router';
+
+/** Item in a `pages` config — either a string id or an `{ id, label }` object. */
+export type PageItem = string | { id: string; label?: string };
+
+/**
+ * Declarative multi-page configuration for a component.
+ *
+ * Pages are **lazy-loaded**: only the active page is fetched on first render.
+ * Remaining pages are prefetched in the background for instant navigation.
+ */
+export interface PagesConfig {
+  /** Directory containing the page HTML files (resolved relative to `base`). */
+  dir?: string;
+  /** Route parameter name to read (e.g. `'section'` for `/docs/:section`). */
+  param?: string;
+  /** Default page id when the param is absent. */
+  default?: string;
+  /** File extension appended to each page id (default `'.html'`). */
+  ext?: string;
+  /** List of page ids and/or `{ id, label }` objects. */
+  items?: PageItem[];
+}
+
+/** The object passed to `$.component()` to define a component. */
+export interface ComponentDefinition {
+  /**
+   * Initial reactive state.
+   * A function form is recommended so each instance gets its own copy.
+   */
+  state?: Record<string, any> | (() => Record<string, any>);
+
+  /**
+   * Returns an HTML string. Called on every state change.
+   * `this` is the component instance.
+   */
+  render?(this: ComponentInstance): string;
+
+  /** CSS string — scoped to the component root on first render. */
+  styles?: string;
+
+  /**
+   * URL (or array / object map of URLs) to external HTML template file(s).
+   * If `render()` is also defined, `render()` takes priority.
+   */
+  templateUrl?: string | string[] | Record<string, string>;
+
+  /**
+   * URL (or array of URLs) to external CSS file(s).
+   * Fetched and auto-scoped on first mount; merged with `styles` if both present.
+   */
+  styleUrl?: string | string[];
+
+  /** High-level multi-page configuration shorthand. */
+  pages?: PagesConfig;
+
+  /**
+   * Override the base path for resolving relative `templateUrl`, `styleUrl`,
+   * and `pages.dir` paths. Normally auto-detected from the calling file.
+   */
+  base?: string;
+
+  /** Called before first render (during construction). */
+  init?(this: ComponentInstance): void;
+
+  /** Called once after first render and DOM insertion. */
+  mounted?(this: ComponentInstance): void;
+
+  /** Called after every subsequent re-render. */
+  updated?(this: ComponentInstance): void;
+
+  /** Called when the component is destroyed. Clean up subscriptions here. */
+  destroyed?(this: ComponentInstance): void;
+
+  /**
+   * Computed properties — lazy getters derived from state.
+   * Each function receives the raw state as its argument.
+   * Access via `this.computed.name` in methods and templates.
+   */
+  computed?: Record<string, (state: Record<string, any>) => any>;
+
+  /**
+   * Watch state keys for changes.
+   * Keys support dot-path notation (e.g. `'user.name'`).
+   * Handler receives `(newValue, oldValue)`.
+   */
+  watch?: Record<
+    string,
+    | ((this: ComponentInstance, newVal: any, oldVal: any) => void)
+    | { handler: (this: ComponentInstance, newVal: any, oldVal: any) => void }
+  >;
+
+  /** Additional keys become instance methods (bound to the instance). */
+  [method: string]: any;
+}
+
+/** The runtime instance of a mounted component. */
+export interface ComponentInstance {
+  /** Reactive state proxy. Mutating triggers re-render. */
+  state: Record<string, any> & ReactiveProxy;
+
+  /**
+   * Frozen props passed from parent / router.
+   * When mounted by the router, includes `$route`, `$query`, and `$params`.
+   */
+  readonly props: Readonly<
+    Record<string, any> & {
+      $route?: NavigationContext;
+      $query?: Record<string, string>;
+      $params?: Record<string, string>;
+    }
+  >;
+
+  /** Map of `z-ref` name → DOM element. Populated after each render. */
+  refs: Record<string, Element>;
+
+  /** Keyed template map (when using multi-`templateUrl` or `pages`). */
+  templates: Record<string, string>;
+
+  /** Normalized page metadata (when using `pages` config). */
+  pages: Array<{ id: string; label: string }>;
+
+  /** Active page id derived from route param (when using `pages` config). */
+  activePage: string;
+
+  /**
+   * Computed properties — lazy getters derived from state.
+   * Defined via `computed` in the component definition.
+   */
+  readonly computed: Record<string, any>;
+
+  /** Merge partial state (triggers re-render). */
+  setState(partial: Record<string, any>): void;
+
+  /** Dispatch a bubbling `CustomEvent` from the component root. */
+  emit(name: string, detail?: any): void;
+
+  /** Teardown: removes listeners, scoped styles, clears DOM. */
+  destroy(): void;
+
+  /**
+   * Manually queue a re-render (microtask-batched).
+   * Safe to call from anywhere — state mutations during render are coalesced.
+   */
+  _scheduleUpdate(): void;
+
+  /** Any user-defined methods from the component definition. */
+  [method: string]: any;
+}
+
+/**
+ * Register a new component.
+ * @param name Must contain a hyphen (Web Component convention).
+ * @param definition Component definition object.
+ */
+export function component(name: string, definition: ComponentDefinition): void;
+
+/**
+ * Mount a registered component into a target element.
+ * @returns The component instance.
+ */
+export function mount(
+  target: string | Element,
+  componentName: string,
+  props?: Record<string, any>,
+): ComponentInstance;
+
+/**
+ * Scan `root` for elements whose tag matches a registered component and mount them.
+ * @param root Defaults to `document.body`.
+ */
+export function mountAll(root?: Element): void;
+
+/** Get the component instance mounted on `target`. */
+export function getInstance(target: string | Element): ComponentInstance | null;
+
+/** Destroy the component at the given target. */
+export function destroy(target: string | Element): void;
+
+/** Returns an object of all registered component definitions (for debugging). */
+export function getRegistry(): Record<string, ComponentDefinition>;
+
+/** Handle returned by `$.style()`. */
+export interface StyleHandle {
+  /** Remove all injected `<link>` elements. */
+  remove(): void;
+  /** Resolves when all stylesheets have loaded. */
+  ready: Promise<void>;
+}
+
+/** Options for `$.style()`. */
+export interface StyleOptions {
+  /** Hide page until loaded to prevent FOUC (default `true`). */
+  critical?: boolean;
+  /** Background color while hidden during critical load (default `'#0d1117'`). */
+  bg?: string;
+}
+
+/**
+ * Dynamically load global (unscoped) stylesheet file(s) into `<head>`.
+ * Relative paths resolve relative to the calling file.
+ */
+export function style(urls: string | string[], opts?: StyleOptions): StyleHandle;

package/types/errors.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Structured error handling — error codes, error class, and global handler.
+ *
+ * @module errors
+ */
+
+/** All structured error codes used by zQuery. */
+export declare const ErrorCode: {
+  // Reactive
+  readonly REACTIVE_CALLBACK: 'ZQ_REACTIVE_CALLBACK';
+  readonly SIGNAL_CALLBACK: 'ZQ_SIGNAL_CALLBACK';
+  readonly EFFECT_EXEC: 'ZQ_EFFECT_EXEC';
+
+  // Expression parser
+  readonly EXPR_PARSE: 'ZQ_EXPR_PARSE';
+  readonly EXPR_EVAL: 'ZQ_EXPR_EVAL';
+  readonly EXPR_UNSAFE_ACCESS: 'ZQ_EXPR_UNSAFE_ACCESS';
+
+  // Component
+  readonly COMP_INVALID_NAME: 'ZQ_COMP_INVALID_NAME';
+  readonly COMP_NOT_FOUND: 'ZQ_COMP_NOT_FOUND';
+  readonly COMP_MOUNT_TARGET: 'ZQ_COMP_MOUNT_TARGET';
+  readonly COMP_RENDER: 'ZQ_COMP_RENDER';
+  readonly COMP_LIFECYCLE: 'ZQ_COMP_LIFECYCLE';
+  readonly COMP_RESOURCE: 'ZQ_COMP_RESOURCE';
+  readonly COMP_DIRECTIVE: 'ZQ_COMP_DIRECTIVE';
+
+  // Router
+  readonly ROUTER_LOAD: 'ZQ_ROUTER_LOAD';
+  readonly ROUTER_GUARD: 'ZQ_ROUTER_GUARD';
+  readonly ROUTER_RESOLVE: 'ZQ_ROUTER_RESOLVE';
+
+  // Store
+  readonly STORE_ACTION: 'ZQ_STORE_ACTION';
+  readonly STORE_MIDDLEWARE: 'ZQ_STORE_MIDDLEWARE';
+  readonly STORE_SUBSCRIBE: 'ZQ_STORE_SUBSCRIBE';
+
+  // HTTP
+  readonly HTTP_REQUEST: 'ZQ_HTTP_REQUEST';
+  readonly HTTP_TIMEOUT: 'ZQ_HTTP_TIMEOUT';
+  readonly HTTP_INTERCEPTOR: 'ZQ_HTTP_INTERCEPTOR';
+  readonly HTTP_PARSE: 'ZQ_HTTP_PARSE';
+
+  // General
+  readonly INVALID_ARGUMENT: 'ZQ_INVALID_ARGUMENT';
+};
+
+/** Union of all error code string values. */
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/** Structured error class used throughout zQuery. */
+export class ZQueryError extends Error {
+  readonly name: 'ZQueryError';
+  /** Machine-readable error code (e.g. `'ZQ_COMP_RENDER'`). */
+  readonly code: ErrorCodeValue;
+  /** Extra contextual data (component name, expression string, etc.). */
+  readonly context: Record<string, any>;
+  /** Original error that caused this one, if any. */
+  readonly cause?: Error;
+
+  constructor(
+    code: ErrorCodeValue,
+    message: string,
+    context?: Record<string, any>,
+    cause?: Error,
+  );
+}
+
+/** Error handler callback type. */
+export type ZQueryErrorHandler = (error: ZQueryError) => void;
+
+/**
+ * Register a global error handler. Called whenever zQuery catches an
+ * error internally. Pass `null` to remove.
+ */
+export function onError(handler: ZQueryErrorHandler | null): void;
+
+/**
+ * Report an error through the global handler and console.
+ * Non-throwing — used for recoverable errors in callbacks, lifecycle hooks, etc.
+ */
+export function reportError(
+  code: ErrorCodeValue,
+  message: string,
+  context?: Record<string, any>,
+  cause?: Error,
+): void;
+
+/**
+ * Wrap a callback so that thrown errors are caught, reported via `reportError`,
+ * and don't crash the current execution context.
+ */
+export function guardCallback<T extends (...args: any[]) => any>(
+  fn: T,
+  code: ErrorCodeValue,
+  context?: Record<string, any>,
+): (...args: Parameters<T>) => ReturnType<T> | undefined;
+
+/**
+ * Validate a required value is defined and of the expected type.
+ * Throws `ZQueryError` with `INVALID_ARGUMENT` on failure.
+ */
+export function validate(value: any, name: string, expectedType?: string): void;