@deijose/nix-js 1.0.5 → 1.0.7

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

@@ -8,7 +8,7 @@ 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 type { Router, RouteRecord, NavigationGuard, NavigationGuardResult, AfterEachHook, ResolvedRoute } from "./router";
 export { suspend, lazy } from "./async";
 export type { SuspenseOptions } from "./async";
 export { provide, inject, createInjectionKey } from "./context";

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

@@ -1,124 +1,30 @@
 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.
- */
+/** Valid child content for components. */
 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");
- */
+/** Base class for components with lifecycle hooks. */
 export declare abstract class NixComponent {
-    /** @internal – marca que identifica instancias NixComponent en el engine. */
+    /** @internal */
     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()`.
-     */
+    /** Default slot — child content injected by the parent. */
     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>`)}`
-     */
+    /** Sets the default slot content. Returns `this` for chaining. */
     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>`)
-     */
+    /** Sets a named slot. Returns `this` for chaining. */
     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>
-     *   `;
-     * }
-     * ```
-     */
+    /** Returns content for a named slot. */
     slot(name: string): NixChildren;
-    /**
-     * Debe implementarse: retorna el template del componente.
-     * Se llama UNA sola vez al montar — las actualizaciones ocurren por signals.
-     */
+    /** Returns the component template. Called once on mount; updates happen via 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);
-     *   }
-     */
+    /** Called before `render()` — no DOM yet. Errors are caught by `onError` if present. */
     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);
-     *   }
-     */
+    /** Called after DOM insertion. May return a cleanup function. */
     onMount?(): (() => void) | void;
-    /**
-     * Llamado ANTES de remover el componente del DOM.
-     * Se ejecuta siempre al desmontar, incluso si no se definió onMount.
-     */
+    /** Called before DOM removal. */
     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.
-     */
+    /** Catches errors thrown in `onInit` and `onMount`. */
     onError?(err: unknown): void;
 }
-/**
- * @internal – Verifica si un valor es una instancia de NixComponent.
- */
+/** @internal */
 export declare function isNixComponent(v: unknown): v is NixComponent;

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

@@ -10,26 +10,13 @@ export declare class Signal<T> {
     private _value;
     private _subs;
     constructor(initialValue: T);
-    /**
-     * Leer el valor.
-     * Si hay un effect activo, se suscribe automáticamente.
-     */
+    /** Read the current value. Subscribes the active effect if one exists. */
     get value(): T;
-    /**
-     * Escribir un nuevo valor.
-     * Si es diferente al actual, notifica a todos los effects suscritos.
-     */
+    /** Write a new value. Notifies subscribers when the value changes. */
     set value(newValue: T);
-    /**
-     * Modificar el valor con una función.
-     *   count.update(n => n + 1)
-     */
+    /** Mutate the value via a updater function. */
     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.
-     */
+    /** Read without subscribing the active effect. */
     peek(): T;
     /** @internal */
     _removeSub(sub: () => void): void;
@@ -38,87 +25,28 @@ export declare class Signal<T> {
 }
 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();
+ * Runs `fn` and re-runs it whenever any signal read inside changes.
+ * Returns a dispose function to tear down the effect.
+ * If `fn` returns a function, it is called as cleanup before each re-run
+ * and on disposal.
  */
 export declare function effect(fn: () => void | (() => void)): () => void;
-/**
- * Valor derivado que se recalcula automáticamente.
- *
- *   const doubled = computed(() => count.value * 2);
- */
+/** Derived signal that recalculates when its dependencies change. */
 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;
- *   });
- */
+/** Groups multiple signal writes so effects flush once at the end. */
 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
- */
+/** Executes `fn` without subscribing to any signals read inside it. */
 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`.
-     */
+    /** Fire the callback immediately with the current value. Default: `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`.
-     */
+    /** Automatically dispose after the first callback invocation. Default: `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
+ * Watches a reactive source and calls `callback(newValue, oldValue)` on each change.
+ * Accepts a Signal or a getter function. Returns a dispose function.
  */
 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());
- */
+/** Returns a promise that resolves on the next microtask. Accepts an optional callback. */
 export declare function nextTick(fn?: () => void): Promise<void>;

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

@@ -8,156 +8,80 @@ import type { NixTemplate } from "./template";
  * - `void` / `undefined` — allow the navigation.
  */
 export type NavigationGuardResult = void | undefined | false | string;
-/**
- * A navigation guard function.
- *
- * @param to   Destination pathname (e.g. `"/admin"`).
- * @param from Current pathname before the navigation.
- * @returns `false` to cancel, a path string to redirect, or nothing to allow.
- *          May return a Promise for async guard logic.
- *
- * @example
- * router.beforeEach((to, from) => {
- *   if (!auth.isLoggedIn && to !== "/login") return "/login";
- * });
- */
+/** Guard function invoked before navigation commits. */
 export type NavigationGuard = (to: string, from: string) => NavigationGuardResult | Promise<NavigationGuardResult>;
 export interface RouteRecord {
-    /**
-     * Segmento de ruta. Soporta:
-     *  - Literal:   "/about", "/users"
-     *  - Parámetro: "/users/:id", "/posts/:slug/comments/:cid"
-     *  - Wildcard:  "*"  (fallback global o de prefijo con children)
-     *
-     * Los paths de children se concatenan con el del padre.
-     *
-     * @example
-     * { path: "/users/:id", component: UserDetail }
-     * // Navegar a "/users/42" → params.value = { id: "42" }
-     *
-     * @example
-     * { path: "/dash", component: DashLayout, children: [
-     *   { path: "/users",   component: UsersPage },
-     * ]}
-     * // Genera las rutas planas: /dash, /dash/users
-     */
+    /** Route path segment. Supports literals, params (`:id`), and wildcards (`*`). */
     path: string;
-    /** Factory que devuelve la vista a renderizar en este nivel */
+    /** Factory returning the view for this route level. */
     component: () => NixTemplate | NixComponent;
-    /**
-     * Rutas hijas. Sus paths se unen con el del padre.
-     * El componente padre debe incluir `new RouterView(1)` para renderizarlas.
-     */
+    /** Child routes. Paths are joined with the parent. */
     children?: RouteRecord[];
-    /**
-     * Guard de nivel de ruta. Se ejecuta solo al entrar en esta ruta concreta.
-     * Misma semántica de retorno que `beforeEach`.
-     *
-     * @example
-     * { path: "/admin", component: () => new AdminPage(),
-     *   beforeEnter: (to, from) => {
-     *     if (!isAdmin) return "/";
-     *   }}
-     */
+    /** Route-level guard. Runs only when entering this specific route. */
     beforeEnter?: NavigationGuard;
 }
+/**
+ * Callback for `afterEach` hooks — receives the committed `to` and `from` paths.
+ */
+export type AfterEachHook = (to: string, from: string) => void;
+/**
+ * Result of `router.resolve(path)` — inspect what would match without navigating.
+ */
+export interface ResolvedRoute {
+    /** Whether the path matched any registered route. */
+    matched: boolean;
+    /** Extracted route params (empty object if no match). */
+    params: Record<string, string>;
+    /** The matched route record, or `undefined` if no match. */
+    route: RouteRecord | undefined;
+}
 export interface Router {
-    /** Señal con la ruta activa actual (pathname, p.ej. "/users/42") */
+    /** Signal with the current active pathname. */
     readonly current: Signal<string>;
-    /**
-     * Señal con los parámetros dinámicos de la ruta activa (:id, :slug…).
-     * Se actualiza síncronamente con cada `navigate()`.
-     *
-     * @example
-     * // Ruta: "/users/:id"  →  navigate("/users/42")
-     * router.params.value  // { id: "42" }
-     */
+    /** Signal with the extracted dynamic route params. */
     readonly params: Signal<Record<string, string>>;
-    /**
-     * Señal con los query params de la URL (?clave=valor…).
-     * Se actualiza síncronamente con cada `navigate()`.
-     *
-     * @example
-     * router.navigate("/users?page=2&sort=name")
-     * router.query.value  // { page: "2", sort: "name" }
-     *
-     * @example
-     * router.navigate("/users", { page: 2, sort: "name" })
-     * router.query.value  // { page: "2", sort: "name" }
-     */
+    /** Signal with the URL query params. */
     readonly query: Signal<Record<string, string>>;
-    /**
-     * Navegar a una ruta nueva (pushState + actualiza señales).
-     * Si hay guards registrados, la navegación espera a que todos pasen.
-     *
-     * @param path     Ruta destino. Puede incluir query string: "/users?page=2"
-     * @param query    Query params como objeto. Se mezclan con los del path.
-     *                 Un valor `null`/`undefined` elimina el parámetro.
-     */
+    /** Navigate to a new path via `pushState`. Guards run before committing. */
     navigate(path: string, query?: Record<string, string | number | boolean | null | undefined>): void;
-    /** Árbol de rutas original (tal como se pasó a createRouter) */
+    /** Navigate via `replaceState` (no new history entry). Guards still run. */
+    replace(path: string, query?: Record<string, string | number | boolean | null | undefined>): void;
+    /** Go back one entry in the browser history. */
+    back(): void;
+    /** Go forward one entry in the browser history. */
+    forward(): void;
+    /** Move `delta` entries in the browser history. */
+    go(delta: number): void;
+    /** Check if `path` is currently active. `exact=false` enables prefix matching. */
+    isActive(path: string, exact?: boolean): boolean;
+    /** Inspect what route would match `path` without navigating. */
+    resolve(path: string): ResolvedRoute;
+    /** Original route tree passed to `createRouter`. */
     readonly routes: RouteRecord[];
-    /**
-     * Registra un guard de navegación global.
-     * Se ejecuta (en orden de registro) antes de cada navegación.
-     *
-     * Retorna una función para eliminar el guard.
-     *
-     * @example
-     * const stop = router.beforeEach((to, from) => {
-     *   if (!auth && to !== "/login") return "/login";
-     * });
-     * stop(); // elimina el guard
-     */
+    /** Register a global navigation guard. Returns a removal function. */
     beforeEach(guard: NavigationGuard): () => void;
+    /** Register a hook that runs after every successful navigation. Returns a removal function. */
+    afterEach(hook: AfterEachHook): () => void;
 }
 /**
- * Crea el router History API y lo establece como singleton activo del módulo.
- * Usa `history.pushState` — URLs limpias sin `#`.
- * `RouterView` y `Link` lo consumen automáticamente — no necesitan que se los pases.
- *
- * @note En producción el servidor debe responder con `index.html` para cualquier
- * ruta no-archivo. Vite dev y `vite preview` lo hacen automáticamente.
+ * Creates the History API router and sets it as the active singleton.
+ * In production the server must serve `index.html` for all non-file routes.
  */
 export declare function createRouter(routes: RouteRecord[]): Router;
-/**
- * Devuelve el router activo (singleton).
- * Útil dentro de componentes para acceder a `params` y `current` sin prop-drilling.
- *
- * @example
- * class UserDetail extends NixComponent {
- *   render() {
- *     return html`<div>User: ${() => useRouter().params.value.id}</div>`;
- *   }
- * }
- */
+/** Returns the active router singleton. */
 export declare function useRouter(): Router;
 /**
  * @internal — Resets the router singleton. Used by tests to avoid
  * "A router already exists" warnings between test cases.
  */
 export declare function _resetRouter(): void;
-/**
- * Renderiza el componente de la ruta activa en el nivel `depth`.
- *
- * - `new RouterView()`  → nivel raíz (depth 0).
- * - `new RouterView(1)` → primer nivel de rutas anidadas. Úsalo dentro del
- *   componente padre para que renderice el hijo correspondiente.
- *
- * Consume el router singleton — no requiere que se le pase el router.
- */
+/** Renders the matched route component at the given nesting `depth`. */
 export declare class RouterView extends NixComponent {
     private _depth;
     constructor(depth?: number);
     render(): NixTemplate;
 }
-/**
- * Enlace de navegación reactivo que se estiliza como activo/inactivo según la
- * ruta actual. Consume el router singleton — no requiere que se le pase.
- *
- * @example
- * new Link("/about", "About")
- */
+/** Reactive navigation link styled as active/inactive based on the current route. */
 export declare class Link extends NixComponent {
     private _to;
     private _label;

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

@@ -1,40 +1,15 @@
 import { Signal } from "./reactivity";
-/** Transforma cada propiedad del estado inicial en su Signal correspondiente. */
+/** Maps each state property to its corresponding Signal. */
 export type StoreSignals<T extends Record<string, unknown>> = {
     readonly [K in keyof T]: Signal<T[K]>;
 };
-/** Tipo del store tal como lo ve el usuario. */
+/** The store as seen by the consumer: signals + actions + `$reset`. */
 export type Store<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>> = StoreSignals<T> & A & {
-    /**
-     * Restaura todos los signals a sus valores iniciales.
-     * Equivalente a hacer `signal.value = initialValue` en cada propiedad.
-     */
+    /** Resets all signals to their initial values. */
     $reset(): void;
 };
 /**
- * Crea un store reactivo global.
- *
- * @param initialState  Objeto plano con los valores iniciales.
- * @param actionsFactory  Función que recibe los signals y retorna acciones.
- *
- * @example
- *   // Sin acciones
- *   const theme = createStore({ dark: false, fontSize: 16 });
- *   theme.dark.value = true;
- *
- * @example
- *   // Con acciones
- *   const cart = createStore(
- *     { items: [] as string[], total: 0 },
- *     (s) => ({
- *       add:    (item: string) => s.items.update(arr => [...arr, item]),
- *       clear:  ()             => cart.$reset(),
- *     })
- *   );
- *
- *   cart.add("Manzana");
- *   cart.items.value;      // ["Manzana"]
- *   cart.clear();
- *   cart.items.value;      // []
+ * Creates a reactive global store. Each property becomes a Signal.
+ * Optional `actionsFactory` receives the signals and returns action methods.
  */
 export declare function createStore<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>>(initialState: T, actionsFactory?: (signals: StoreSignals<T>) => A): Store<T, A>;