@deijose/nix-js 1.0.3 → 1.0.5

package/dist/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { Signal, signal, effect, computed, batch, watch, untrack, nextTick, html, repeat, ref, showWhen, portal, createPortalOutlet, portalOutlet, provideOutlet, injectOutlet, createErrorBoundary, transition, mount, NixComponent, createStore, createRouter, RouterView, Link, useRouter, suspend, lazy, provide, inject, createInjectionKey, useField, createForm, required, minLength, maxLength, email, pattern, min, max, createValidator, validators, extendValidators, } from "./nix";
+export type { WatchOptions, NixTemplate, NixMountHandle, KeyedList, NixRef, PortalOutlet, ErrorFallback, TransitionOptions, TransitionContent, Store, StoreSignals, Router, RouteRecord, NavigationGuard, NavigationGuardResult, SuspenseOptions, InjectionKey, Validator, FieldState, FieldErrors, FormState, FormOptions, ValidatorsBase, NixChildren, } from "./nix";

package/dist/lib/nix/async.d.ts

@@ -0,0 +1,69 @@
+import { NixComponent } from "./lifecycle";
+import type { NixTemplate } from "./template";
+export interface SuspenseOptions {
+    /**
+     * Template a mostrar mientras la promesa está pendiente.
+     * Por defecto: spinner de puntos animados.
+     */
+    fallback?: NixTemplate;
+    /**
+     * Factory que recibe el error y devuelve el template de error.
+     * Por defecto: mensaje de error en rojo.
+     */
+    errorFallback?: (err: unknown) => NixTemplate;
+    /**
+     * Si `true`, mantiene el fallback visible mientras `asyncFn` vuelve a
+     * ejecutarse tras un cambio reactivo. Si `false` (por defecto), durante
+     * las recargas se sigue mostrando el contenido anterior hasta que la nueva
+     * promesa se resuelva.
+     */
+    resetOnRefresh?: boolean;
+}
+/**
+ * Ejecuta una función async y renderiza según su estado (pending / resolved /
+ * error). Equivale al patrón <Suspense> de otros frameworks.
+ *
+ * @param asyncFn   Función que devuelve una promesa con los datos.
+ * @param renderFn  Recibe los datos resueltos y devuelve el template/componente.
+ * @param options   `fallback`, `errorFallback`, `resetOnRefresh`.
+ *
+ * @example
+ * // Uso simple con fallback por defecto
+ * const userView = suspend(
+ *   () => fetchUser(userId.value),
+ *   user => html`<div>${user.name}</div>`
+ * );
+ *
+ * @example
+ * // Con fallback personalizado y manejo de error
+ * suspend(
+ *   () => api.getItems(),
+ *   items => html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`,
+ *   {
+ *     fallback: html`<span>Cargando items…</span>`,
+ *     errorFallback: err => html`<p style="color:red">Error: ${String(err)}</p>`,
+ *   }
+ * )
+ */
+export declare function suspend<T>(asyncFn: () => Promise<T>, renderFn: (data: T) => NixTemplate | NixComponent, options?: SuspenseOptions): NixComponent;
+/**
+ * Envuelve un import dinámico para lazy loading de componentes de ruta.
+ * El módulo se carga una sola vez (cacheado) y mientras tanto muestra el
+ * fallback. Compatible directamente con el campo `component` de `RouteRecord`.
+ *
+ * El módulo importado debe exportar el componente como **export default**.
+ *
+ * @param importFn  Función que hace el import dinámico.
+ * @param fallback  Template opcional mientras se descarga el chunk.
+ *
+ * @example
+ * createRouter([
+ *   { path: "/",      component: lazy(() => import("./pages/Home"))    },
+ *   { path: "/about", component: lazy(() => import("./pages/About"))   },
+ *   { path: "/admin", component: lazy(() => import("./pages/Admin"),
+ *       html`<p>Cargando panel…</p>`) },
+ * ])
+ */
+export declare function lazy(importFn: () => Promise<{
+    default: new () => NixComponent;
+}>, fallback?: NixTemplate): () => NixComponent;

package/dist/lib/nix/component.d.ts

@@ -0,0 +1,13 @@
+import type { NixTemplate, NixMountHandle } from "./template";
+import { type NixComponent } from "./lifecycle";
+/**
+ * Monta un NixTemplate o NixComponent en el DOM.
+ *
+ *   mount(App(), "#app");           // NixTemplate (función componente)
+ *   mount(new Timer(), "#app");     // NixComponent (clase con lifecycle)
+ *
+ * @param component NixTemplate (resultado de html``) o instancia de NixComponent.
+ * @param container Selector CSS o HTMLElement donde se insertará.
+ * @returns         { unmount() } para limpiar effects y remover el DOM.
+ */
+export declare function mount(component: NixTemplate | NixComponent, container: Element | string): NixMountHandle;

package/dist/lib/nix/context.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Clave tipada para provide/inject.
+ * El parámetro genérico T garantiza coherencia entre proveedor y consumidor.
+ *
+ * @example
+ *   const THEME_KEY = createInjectionKey<Signal<string>>("theme");
+ */
+export type InjectionKey<T> = symbol & {
+    readonly __nixType?: T;
+};
+/**
+ * Crea una InjectionKey única y tipada.
+ * Cada llamada produce un símbolo distinto, evitando colisiones.
+ *
+ * @param description Nombre descriptivo (aparece en Symbol.toString())
+ */
+export declare function createInjectionKey<T>(description?: string): InjectionKey<T>;
+/** @internal — devuelve copia del stack (para capturar en closures de efectos). */
+export declare function _captureContextSnapshot(): Map<unknown, unknown>[];
+/** @internal — push de un contexto vacío para un nuevo componente (render estático). */
+export declare function _pushComponentContext(): void;
+/** @internal — pop del contexto del componente actual (render estático). */
+export declare function _popComponentContext(): void;
+/**
+ * @internal — ejecuta `fn` con `parentSnapshot` como ancestros y un nuevo
+ * contexto vacío en el tope, luego restaura el stack previo.
+ *
+ * Usado por efectos reactivos que pueden re-ejecutarse fuera del árbol de
+ * rendering original (p.ej. NixComponents dentro de `() => new MyComp()`).
+ */
+export declare function _withComponentContext<T>(parentSnapshot: Map<unknown, unknown>[], fn: () => T): T;
+/**
+ * Registra un valor para que los componentes descendientes puedan obtenerlo
+ * con `inject()`.
+ *
+ * Debe llamarse en `onInit()` o en el constructor de un `NixComponent`.
+ * Si se llama fuera del contexto de render de un componente, lanza un error.
+ *
+ * @example
+ *   class ThemeProvider extends NixComponent {
+ *     theme = signal("dark");
+ *     onInit() { provide(THEME_KEY, this.theme); }   // ← aquí
+ *     render()  { return html`${new ThemedButton()}`; }
+ *   }
+ */
+export declare function provide<T>(key: InjectionKey<T> | string | symbol, value: T): void;
+/**
+ * Obtiene un valor provisto por un componente ancestro.
+ * Busca de hijo a padre; retorna `undefined` si la clave no fue provista.
+ *
+ * Úsalo como propiedad de clase o dentro de `onInit()`.
+ *
+ * @example
+ *   class ThemedButton extends NixComponent {
+ *     theme = inject(THEME_KEY);   // Signal<string> | undefined
+ *     render() {
+ *       return html`<button class=${() => this.theme?.value ?? "light"}>OK</button>`;
+ *     }
+ *   }
+ */
+export declare function inject<T>(key: InjectionKey<T> | string | symbol): T | undefined;

package/dist/lib/nix/form.d.ts

@@ -0,0 +1,258 @@
+import type { Signal } from "./reactivity";
+/** A validator function. Return an error string, or null/undefined if valid. */
+export type Validator<T> = (value: T) => string | null | undefined;
+export declare function required(message?: string): Validator<unknown>;
+export declare function minLength(n: number, message?: string): Validator<string>;
+export declare function maxLength(n: number, message?: string): Validator<string>;
+export declare function pattern(regex: RegExp, message?: string): Validator<string>;
+export declare function email(message?: string): Validator<string>;
+export declare function min(n: number, message?: string): Validator<number>;
+export declare function max(n: number, message?: string): Validator<number>;
+/**
+ * Creates a typed custom validator, fully compatible with `useField` and
+ * `createForm`. The preferred way to define your own rules without importing
+ * the `Validator<T>` type manually.
+ *
+ * @example Simple rule
+ * ```typescript
+ * const noSpaces = createValidator<string>((v) =>
+ *   v.includes(" ") ? "No spaces allowed" : null
+ * );
+ *
+ * useField("", [noSpaces]);
+ * ```
+ *
+ * @example Configurable rule (same pattern as built-ins)
+ * ```typescript
+ * const phone = (msg = "Invalid phone number") =>
+ *   createValidator<string>((v) =>
+ *     /^\+?\d{7,15}$/.test(v) ? null : msg
+ *   );
+ *
+ * useField("", [phone()]);
+ * useField("", [phone("Enter your mobile number")]);
+ * ```
+ */
+export declare function createValidator<T>(fn: (value: T) => string | null | undefined): Validator<T>;
+/**
+ * All built-in validators grouped as a namespace object.
+ *
+ * Use this when you prefer `validators.required()` over individual named
+ * imports. Combine with `extendValidators` to add your own rules.
+ *
+ * @example
+ * ```typescript
+ * import { validators } from "@deijose/nix-js";
+ *
+ * createForm(
+ *   { name: "", email: "", age: 0 },
+ *   {
+ *     validators: {
+ *       name:  [validators.required(), validators.minLength(2)],
+ *       email: [validators.required(), validators.email()],
+ *       age:   [validators.required(), validators.min(18)],
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare const validators: {
+    readonly required: typeof required;
+    readonly minLength: typeof minLength;
+    readonly maxLength: typeof maxLength;
+    readonly email: typeof email;
+    readonly pattern: typeof pattern;
+    readonly min: typeof min;
+    readonly max: typeof max;
+};
+/** Shape of the built-in `validators` namespace. Used as the base type for `extendValidators`. */
+export type ValidatorsBase = typeof validators;
+/**
+ * Merges your own validator factories into the `validators` namespace, returning
+ * a fully typed object that includes both built-ins and custom rules.
+ *
+ * The original `validators` object is **never mutated** — a new object is returned.
+ *
+ * @example
+ * ```typescript
+ * import { validators, extendValidators, createValidator } from "@deijose/nix-js";
+ *
+ * const myValidators = extendValidators(validators, {
+ *   // Configurable rule (custom message support)
+ *   phone: (msg = "Invalid phone number") =>
+ *     createValidator<string>((v) => /^\+?\d{7,15}$/.test(v) ? null : msg),
+ *
+ *   // Rule reusing a built-in internally
+ *   slug: (msg = "Only lowercase letters, numbers and hyphens") =>
+ *     createValidator<string>((v) =>
+ *       /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v) ? null : msg
+ *     ),
+ * });
+ *
+ * // IDE auto-complete covers built-ins and custom rules alike:
+ * myValidators.required()        // ✅ built-in
+ * myValidators.email()           // ✅ built-in
+ * myValidators.phone()           // ✅ custom
+ * myValidators.slug("Bad slug")  // ✅ custom, custom message
+ *
+ * // Use in a form like any other validators:
+ * createForm(
+ *   { phone: "", slug: "" },
+ *   {
+ *     validators: {
+ *       phone: [myValidators.required(), myValidators.phone()],
+ *       slug:  [myValidators.required(), myValidators.slug()],
+ *     },
+ *   }
+ * );
+ * ```
+ *
+ * @param base       The base validators namespace (pass `validators`).
+ * @param extensions An object whose values are validator factory functions.
+ * @returns          A new merged namespace object.
+ */
+export declare function extendValidators<E extends Record<string, (...args: any[]) => Validator<any>>>(base: ValidatorsBase, extensions: E): ValidatorsBase & E;
+/** Public state of a single form field. */
+export interface FieldState<T> {
+    /** Current value — read/write signal. */
+    value: Signal<T>;
+    /**
+     * Current error message, or null.
+     * Only non-null after the field has been touched (blur) or dirtied (input).
+     */
+    readonly error: Signal<string | null>;
+    /** True after the input has lost focus at least once. */
+    touched: Signal<boolean>;
+    /** True after the user has typed at least once. */
+    dirty: Signal<boolean>;
+    /** Attach to `@input` on any `<input>`, `<select>`, `<textarea>`. */
+    readonly onInput: (e: Event) => void;
+    /** Attach to `@blur`. */
+    readonly onBlur: () => void;
+    /** Reset to initial value and clear touched/dirty/error state. */
+    reset(): void;
+    /**
+     * @internal — inject an external error message (server / schema validator).
+     * The error clears automatically when the user next edits the field.
+     */
+    _setExternalError(msg: string | null): void;
+}
+/**
+ * Creates a standalone reactive form field with optional validators.
+ *
+ * @example
+ * const name = useField("", [required(), minLength(2)]);
+ *
+ * html`
+ *   <input value=${() => name.value.value}
+ *          @input=${name.onInput}
+ *          @blur=${name.onBlur} />
+ *   ${() => name.error.value
+ *     ? html`<p class="err">${name.error.value}</p>`
+ *     : null}
+ * `
+ */
+export declare function useField<T>(initialValue: T, validators?: Validator<T>[]): FieldState<T>;
+/** Map of field-name → error message for external validation results. */
+export type FieldErrors<T extends Record<string, unknown>> = {
+    [K in keyof T]?: string | null;
+};
+export interface FormState<T extends Record<string, unknown>> {
+    /** Individual field states — access value, error, event handlers. */
+    fields: {
+        [K in keyof T]: FieldState<T[K]>;
+    };
+    /** Computed snapshot of all current field values. */
+    readonly values: Signal<T>;
+    /** Computed map of all currently visible field errors. */
+    readonly errors: Signal<FieldErrors<T>>;
+    /** True when no field has a visible error (meaningful after submit / touch-all). */
+    readonly valid: Signal<boolean>;
+    /** True when at least one field has been modified. */
+    readonly dirty: Signal<boolean>;
+    /**
+     * Wraps a submit callback. Returned handler:
+     * 1. Calls `e.preventDefault()`
+     * 2. Touches all fields (revealing validation errors)
+     * 3. Runs `options.validate` if provided (Zod, etc.)
+     * 4. Only calls `fn(values)` if all validations pass
+     */
+    handleSubmit(fn: (values: T) => void | Promise<void>): (e: Event) => void;
+    /** Reset all fields to their initial values. */
+    reset(): void;
+    /**
+     * Inject external errors (e.g., from a server response) into specific fields.
+     * Each field's error clears automatically the next time the user edits it.
+     *
+     * @example
+     * form.setErrors({ email: "Email already in use" });
+     */
+    setErrors(errors: FieldErrors<T>): void;
+}
+export interface FormOptions<T extends Record<string, unknown>> {
+    /** Per-field built-in validators. */
+    validators?: {
+        [K in keyof T]?: Validator<T[K]>[];
+    };
+    /**
+     * Optional schema-level validator — runs on submit after built-in validators pass.
+     * Return `null` / `undefined` if valid, or a field→error map if not.
+     * String arrays are accepted (first element shown per field).
+     *
+     * @example Zod interop
+     * ```typescript
+     * validate(values) {
+     *   const r = schema.safeParse(values);
+     *   if (r.success) return null;
+     *   return Object.fromEntries(
+     *     Object.entries(r.error.flatten().fieldErrors)
+     *           .map(([k, v]) => [k, v?.[0]])
+     *   );
+     * }
+     * ```
+     *
+     * @example Valibot interop
+     * ```typescript
+     * validate(values) {
+     *   const r = safeParse(schema, values);
+     *   if (r.success) return null;
+     *   const errs: Record<string, string> = {};
+     *   for (const issue of r.issues)
+     *     if (issue.path?.[0]?.key) errs[issue.path[0].key as string] = issue.message;
+     *   return errs;
+     * }
+     * ```
+     */
+    validate?: (values: T) => {
+        [K in keyof T]?: string | string[] | null | undefined;
+    } | null | undefined;
+}
+/**
+ * Creates a managed form with reactive fields, built-in validation,
+ * schema-level validation (Zod / Valibot / Yup / custom), and submit handling.
+ *
+ * @example
+ * const form = createForm(
+ *   { name: "", email: "", age: 0 },
+ *   {
+ *     validators: {
+ *       name:  [required(), minLength(2)],
+ *       email: [required(), email()],
+ *       age:   [required(), min(18)],
+ *     },
+ *   }
+ * );
+ *
+ * html`
+ *   <form @submit=${form.handleSubmit(onSubmit)}>
+ *     <input value=${() => form.fields.name.value.value}
+ *            @input=${form.fields.name.onInput}
+ *            @blur=${form.fields.name.onBlur} />
+ *     ${() => form.fields.name.error.value
+ *       ? html`<p class="err">${form.fields.name.error.value}</p>`
+ *       : null}
+ *     <button type="submit">Submit</button>
+ *   </form>
+ * `
+ */
+export declare function createForm<T extends Record<string, unknown>>(initialValues: T, options?: FormOptions<T>): FormState<T>;

package/dist/lib/nix/index.d.ts

@@ -0,0 +1,17 @@
+export { Signal, signal, effect, computed, batch, watch, untrack, nextTick } from "./reactivity";
+export type { WatchOptions } from "./reactivity";
+export { html, repeat, ref, showWhen, portal, createPortalOutlet, portalOutlet, provideOutlet, injectOutlet, createErrorBoundary, transition } from "./template";
+export type { NixTemplate, NixMountHandle, KeyedList, NixRef, PortalOutlet, ErrorFallback, TransitionOptions, TransitionContent } from "./template";
+export { mount } from "./component";
+export { NixComponent } from "./lifecycle";
+export type { NixChildren } from "./lifecycle";
+export { createStore } from "./store";
+export type { Store, StoreSignals } from "./store";
+export { createRouter, RouterView, Link, useRouter } from "./router";
+export type { Router, RouteRecord, NavigationGuard, NavigationGuardResult } from "./router";
+export { suspend, lazy } from "./async";
+export type { SuspenseOptions } from "./async";
+export { provide, inject, createInjectionKey } from "./context";
+export type { InjectionKey } from "./context";
+export { useField, createForm, required, minLength, maxLength, email, pattern, min, max, createValidator, validators, extendValidators, } from "./form";
+export type { Validator, FieldState, FieldErrors, FormState, FormOptions, ValidatorsBase } from "./form";

package/dist/lib/nix/lifecycle.d.ts

@@ -0,0 +1,124 @@
+import type { NixTemplate } from "./template";
+/**
+ * Tipos válidos para pasar como children a un componente.
+ * Acepta un template, un componente, arrays de ellos, o nada.
+ */
+export type NixChildren = NixTemplate | NixComponent | Array<NixTemplate | NixComponent> | null | undefined;
+/**
+ * Clase base para componentes con lifecycle.
+ *
+ * Implementa `render()` y haz override de los hooks que necesites.
+ *
+ * @example
+ *   class Timer extends NixComponent {
+ *     ticks = signal(0);
+ *
+ *     onMount() {
+ *       const id = setInterval(() => this.ticks.update(n => n + 1), 1000);
+ *       return () => clearInterval(id);   // cleanup automático al desmontar
+ *     }
+ *
+ *     render() {
+ *       return html`<span>${() => this.ticks.value}s</span>`;
+ *     }
+ *   }
+ *
+ *   mount(new Timer(), "#app");
+ */
+export declare abstract class NixComponent {
+    /** @internal – marca que identifica instancias NixComponent en el engine. */
+    readonly __isNixComponent: true;
+    /**
+     * Slot por defecto — contenido hijo que el componente padre inyecta.
+     *
+     * Úsalo en `render()` como cualquier valor interpolado:
+     * ```typescript
+     * render() {
+     *   return html`<div class="card">${this.children}</div>`;
+     * }
+     * ```
+     * Se puede asignar directamente o con el método fluido `setChildren()`.
+     */
+    children?: NixChildren;
+    /** @internal */
+    private _slots;
+    /**
+     * Asigna el slot por defecto. Versión fluida de `this.children = content`.
+     * @returns `this` para encadenar con `setSlot()`.
+     *
+     * @example
+     *   html`${new Card().setChildren(html`<p>Body</p>`)}`
+     */
+    setChildren(content: NixChildren): this;
+    /**
+     * Asigna un slot con nombre. El componente lo lee con `this.slot(name)`.
+     * @returns `this` para encadenar.
+     *
+     * @example
+     *   new Card()
+     *     .setSlot("header", html`<h1>Título</h1>`)
+     *     .setSlot("footer", html`<small>Footer</small>`)
+     *     .setChildren(html`<p>Cuerpo</p>`)
+     */
+    setSlot(name: string, content: NixChildren): this;
+    /**
+     * Obtiene el contenido de un slot con nombre.
+     * Úsalo dentro de `render()`:
+     * ```typescript
+     * render() {
+     *   return html`
+     *     <div>
+     *       <header>${this.slot("header")}</header>
+     *       <main>${this.children}</main>
+     *       <footer>${this.slot("footer")}</footer>
+     *     </div>
+     *   `;
+     * }
+     * ```
+     */
+    slot(name: string): NixChildren;
+    /**
+     * Debe implementarse: retorna el template del componente.
+     * Se llama UNA sola vez al montar — las actualizaciones ocurren por signals.
+     */
+    abstract render(): NixTemplate;
+    /**
+     * Llamado ANTES de `render()` — sin DOM todavía.
+     * Útil para inicializar estado complejo derivado de props u otras
+     * operaciones síncronas que render() necesita.
+     *
+     * Los errores aquí son capturados por `onError` si está implementado.
+     *
+     * @example
+     *   onInit() {
+     *     this.derived = computed(() => this.base.value * 2);
+     *   }
+     */
+    onInit?(): void;
+    /**
+     * Llamado DESPUÉS de que el componente se inserta en el DOM.
+     * Si retorna una función, se usa como cleanup automático al desmontar.
+     *
+     * @example
+     *   onMount() {
+     *     const id = setInterval(() => this.count.update(n => n + 1), 1000);
+     *     return () => clearInterval(id);
+     *   }
+     */
+    onMount?(): (() => void) | void;
+    /**
+     * Llamado ANTES de remover el componente del DOM.
+     * Se ejecuta siempre al desmontar, incluso si no se definió onMount.
+     */
+    onUnmount?(): void;
+    /**
+     * Captura errores lanzados dentro de `onMount`.
+     * Si se implementa, el error queda absorbido y el componente permanece montado.
+     * Si no se implementa, el error se re-lanza.
+     */
+    onError?(err: unknown): void;
+}
+/**
+ * @internal – Verifica si un valor es una instancia de NixComponent.
+ */
+export declare function isNixComponent(v: unknown): v is NixComponent;

package/dist/lib/nix/reactivity.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @internal — Register an error boundary handler. All `effect()` calls made
+ * synchronously while this handler is active will capture it. When those
+ * effects re-run and throw, the captured handler is invoked.
+ */
+export declare function _pushErrorHandler(h: (err: unknown) => void): void;
+/** @internal — Restore the previous error boundary handler. */
+export declare function _popErrorHandler(): void;
+export declare class Signal<T> {
+    private _value;
+    private _subs;
+    constructor(initialValue: T);
+    /**
+     * Leer el valor.
+     * Si hay un effect activo, se suscribe automáticamente.
+     */
+    get value(): T;
+    /**
+     * Escribir un nuevo valor.
+     * Si es diferente al actual, notifica a todos los effects suscritos.
+     */
+    set value(newValue: T);
+    /**
+     * Modificar el valor con una función.
+     *   count.update(n => n + 1)
+     */
+    update(fn: (current: T) => T): void;
+    /**
+     * Leer SIN suscribirse.
+     * Útil cuando necesitas el valor pero no quieres
+     * que el effect se re-ejecute si cambia.
+     */
+    peek(): T;
+    /** @internal */
+    _removeSub(sub: () => void): void;
+    private _notify;
+    dispose(): void;
+}
+export declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * Ejecuta una función y la RE-EJECUTA cada vez que
+ * algún signal leído dentro de ella cambie.
+ *
+ * Retorna una función dispose() para destruir el effect.
+ *
+ *   const dispose = effect(() => {
+ *     console.log(count.value);
+ *     return () => console.log("cleanup");
+ *   });
+ *
+ *   dispose();
+ */
+export declare function effect(fn: () => void | (() => void)): () => void;
+/**
+ * Valor derivado que se recalcula automáticamente.
+ *
+ *   const doubled = computed(() => count.value * 2);
+ */
+export declare function computed<T>(fn: () => T): Signal<T>;
+/**
+ * Agrupa múltiples cambios para que los effects
+ * se ejecuten UNA sola vez al final.
+ *
+ *   batch(() => {
+ *     x.value = 1;
+ *     y.value = 2;
+ *   });
+ */
+export declare function batch(fn: () => void): void;
+/**
+ * Ejecuta `fn` sin suscribirse a ninguna signal que lea dentro de ella.
+ * Útil para leer valores reactivos sin que esas lecturas re-disparen el
+ * efecto actual (p.ej. en callbacks de `watch`).
+ *
+ *   const total = untrack(() => price.value * qty.value); // no se suscribe
+ */
+export declare function untrack<T>(fn: () => T): T;
+export interface WatchOptions {
+    /**
+     * Si es `true`, el callback se ejecuta inmediatamente con el valor
+     * actual antes de que haya ningún cambio.  Por defecto: `false`.
+     */
+    immediate?: boolean;
+    /**
+     * Si es `true`, el watcher se elimina automáticamente después de la
+     * primera vez que el callback se dispara.  Por defecto: `false`.
+     */
+    once?: boolean;
+}
+/**
+ * Observa una fuente reactiva y ejecuta `callback(newValue, oldValue)` cada
+ * vez que cambia.
+ *
+ * La fuente puede ser:
+ *  - Un getter: `() => count.value + other.value`
+ *  - Una Signal directamente: `count`
+ *
+ * Retorna una función `dispose()` para detener la observación.
+ *
+ * @example
+ * const stop = watch(
+ *   () => user.value.name,
+ *   (newName, oldName) => console.log(newName, oldName),
+ *   { immediate: true }
+ * );
+ * stop(); // deja de observar
+ */
+export declare function watch<T>(source: Signal<T> | (() => T), callback: (newValue: T, oldValue: T | undefined) => void, options?: WatchOptions): () => void;
+/**
+ * Espera a que todos los efectos síncronos pendientes hayan corrido y el
+ * DOM esté actualizado, devolviendo una promesa que resuelve en el próximo
+ * microtask.
+ *
+ * Úsala cuando necesitas leer el DOM *después* de un cambio reactivo:
+ *
+ *   count.value++;
+ *   await nextTick();
+ *   console.log(el.textContent); // ya refleja el nuevo valor
+ *
+ * También acepta un callback opcional:
+ *
+ *   nextTick(() => el.focus());
+ */
+export declare function nextTick(fn?: () => void): Promise<void>;