@deijose/nix-js 1.0.5 → 1.0.7

package/README.md

@@ -1,322 +1,89 @@
-# ❄️ Nix.js
+# Nix.js
 
-A lightweight, fully reactive micro-framework for building modern web UIs — no virtual DOM, no compiler, no build-time magic. Just signals, tagged templates, and pure TypeScript.
+[![npm version](https://img.shields.io/npm/v/@deijose/nix-js.svg)](https://www.npmjs.com/package/@deijose/nix-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-152%20passing-brightgreen.svg)]()
+[![Bundle size](https://img.shields.io/badge/min%2Bgzip-~8%20KB-orange.svg)]()
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)]()
 
-The `@deijose/nix-js` package provides everything you need to build reactive UIs: signals, template engine, components, stores, router, and dependency injection in a single zero-dependency bundle.
+A lightweight, fully reactive micro-framework for building modern web UIs — no virtual DOM, no compiler, no build-time magic. Just signals, tagged templates, and pure TypeScript.
 
 ```
-~14 KB minified · zero dependencies · TypeScript-first · ES2022
+~24 KB minified · ~8 KB gzipped · zero dependencies · TypeScript-first · ES2022
 ```
 
 ## Installation
 
 ```bash
 npm install @deijose/nix-js
-# or
-bun add @deijose/nix-js
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-import { signal, html, mount } from "@deijose/nix-js";
+import { signal, html, NixComponent, mount, createRouter, RouterView, Link, useRouter } from "@deijose/nix-js";
 
-function Counter() {
-  const count = signal(0);
+// --- Reactive counter ---
 
-  return html`
-    <div>
-      <h1>${() => count.value}</h1>
-      <button @click=${() => count.value++}>Increment</button>
-    </div>
-  `;
+class HomePage extends NixComponent {
+  render() {
+    const count = signal(0);
+    return html`
+      <h1>Home</h1>
+      <p>Count: ${() => count.value}</p>
+      <button @click=${() => count.value++}>+1</button>
+    `;
+  }
 }
 
-mount(Counter, document.getElementById("app")!);
-```
-
-### Signals & reactivity
-
-```typescript
-import { signal, computed, effect, watch } from "@deijose/nix-js";
-
-const price = signal(10);
-const qty   = signal(3);
-const total = computed(() => price.value * qty.value);
-
-effect(() => console.log("Total:", total.value)); // logs on every change
-
-watch(total, (next, prev) => console.log(prev, "→", next));
-
-price.value = 20; // effect & watch fire automatically
-```
-
-### Components
-
-```typescript
-import { NixComponent, mount, html } from "@deijose/nix-js";
-import { signal } from "@deijose/nix-js";
-
-class MyComponent extends NixComponent {
-  private msg = signal("Hello");
-
-  onInit() {
-    setTimeout(() => (this.msg.value = "World"), 1000);
-  }
+// --- Dynamic route params ---
 
+class UserPage extends NixComponent {
   render() {
-    return html`<p>${() => this.msg.value}</p>`;
+    const router = useRouter();
+    return html`<h1>User: ${() => router.params.value.id}</h1>`;
   }
 }
 
-mount(MyComponent, document.body);
-```
-
-### Stores
+// --- Router + App shell ---
 
-```typescript
-import { createStore } from "@deijose/nix-js";
-
-const counter = createStore({ count: 0 }, (state) => ({
-  increment() { state.count.value++; },
-  reset()     { state.count.value = 0; },
-}));
-
-counter.count.value; // reactive signal
-counter.increment();
-```
-
-### Router
-
-```typescript
-import { createRouter, RouterView, Link, html } from "@deijose/nix-js";
-
-const router = createRouter([
-  { path: "/",       component: Home },
-  { path: "/about",  component: About },
+createRouter([
+  { path: "/",         component: () => new HomePage() },
+  { path: "/user/:id", component: () => new UserPage() },
 ]);
 
-const App = () => html`
-  <nav>
-    ${Link({ href: "/" },      "Home")}
-    ${Link({ href: "/about" }, "About")}
-  </nav>
-  ${RouterView(router)}
-`;
-```
-
-### Forms
-
-```typescript
-import { createForm, required, email, minLength, min } from "@deijose/nix-js";
-
-const form = createForm(
-  { name: "", email: "", age: 0 },
-  {
-    validators: {
-      name:  [required(), minLength(2)],
-      email: [required(), email()],
-      age:   [required(), min(18)],
-    },
-    // Optional: plug in Zod, Valibot, Yup, or any schema library
-    validate(values) {
-      const r = zodSchema.safeParse(values);
-      if (r.success) return null;
-      return Object.fromEntries(
-        Object.entries(r.error.flatten().fieldErrors).map(([k, v]) => [k, v?.[0]])
-      );
-    },
-  }
-);
-
-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>
-`
-
-// Inject server errors after a failed API call:
-form.setErrors({ email: "Email already in use" });
-```
-
-### Children & slots
-
-```typescript
-import type { NixChildren } from "@deijose/nix-js";
-
-class Card extends NixComponent {
+class App extends NixComponent {
   render() {
     return html`
-      <div class="card">
-        <header>${this.slot("header")}</header>
-        <main>${this.children}</main>
-        <footer>${this.slot("footer") ?? html`<small>Footer</small>`}</footer>
-      </div>
+      <nav>${new Link("/", "Home")} ${new Link("/user/42", "User 42")}</nav>
+      ${new RouterView()}
     `;
   }
 }
 
-const app = new Card()
-  .setSlot("header", html`<h1>Título</h1>`)
-  .setChildren(html`<p>Cuerpo del card</p>`)
-  .setSlot("footer", html`<small>© 2026</small>`);
-
-// Function component style:
-function Box({ children }: { children?: NixChildren }) {
-  return html`<div class="box">${children}</div>`;
-}
+mount(new App(), "#app");
 ```
 
-### show / hide directive
+## What's Included
 
-Toggle visibility **without unmounting** — the element stays in the DOM,
-preserving its state, listeners, and child components.
+Everything ships in a single zero-dependency import:
 
-```typescript
-import { signal } from "@deijose/nix-js";
-
-const isOpen  = signal(false);
-const loading = signal(false);
-
-html`
-  <!-- visible when truthy -->
-  <div show=${() => isOpen.value}>Panel content (kept in DOM)</div>
-
-  <!-- hidden when truthy (inverse of show) -->
-  <form hide=${() => loading.value}>...</form>
-  <div show=${() => loading.value}>⏳ Submitting…</div>
-`
-```
-
-Imperative use outside a template:
-
-```typescript
-import { showWhen, effect } from "@deijose/nix-js";
-
-const panel = document.getElementById("panel") as HTMLElement;
-effect(() => showWhen(panel, isOpen.value));
-```
-
-### Portal
-
-Render a template into `document.body` (or any target) — escaping
-`overflow: hidden` and stacking contexts. Ideal for modals, tooltips, toasts.
-The portal is cleaned up automatically when its parent unmounts.
-
-```typescript
-import { signal, portal, html } from "@deijose/nix-js";
-
-const isOpen = signal(false);
-
-html`
-  <button @click=${() => { isOpen.value = true; }}>Open modal</button>
-
-  ${() => isOpen.value
-    ? portal(html`
-        <div class="overlay" @click=${() => { isOpen.value = false; }}>
-          <div class="modal" @click.stop=${() => {}}>
-            <h2>Hello!</h2>
-            <button @click=${() => { isOpen.value = false; }}>Close</button>
-          </div>
-        </div>
-      `)  // renders into document.body by default
-    : null
-  }
-`
-
-// Custom target:
-portal(html`<div class="toast">Saved!</div>`, "#toast-root")
-portal(html`<Tooltip />`, document.getElementById("tooltip-layer")!)
-```
-
-### Error Boundaries
-
-```typescript
-import { createErrorBoundary, html, mount, signal } from "@deijose/nix-js";
-
-// Catch render and reactive errors in a subtree
-mount(
-  createErrorBoundary(
-    html`<div>${() => riskyData()}</div>`,
-    (err) => html`<div class="error">Failed: ${String(err)}</div>`
-  ),
-  "#app"
-);
-
-// Catches onInit / render / onMount / reactive effects
-createErrorBoundary(new DataWidget(), html`<p>Service unavailable</p>`)
-
-// Nested: inner catches first, outer is app-level
-createErrorBoundary(
-  html`
-    ${createErrorBoundary(new RiskyWidget(), html`<p>Widget error</p>`)}
-  `,
-  html`<p>App crashed</p>`
-)
-```
-
-### Transitions
-
-```typescript
-import { signal, html, transition, mount } from "@deijose/nix-js";
-
-const show = signal(true);
-
-/* CSS in your stylesheet:
-   .fade-enter-active, .fade-leave-active { transition: opacity 0.3s ease; }
-   .fade-enter-from,   .fade-leave-to     { opacity: 0; }
-*/
-
-mount(
-  transition(
-    () => show.value ? html`<p>Hello!</p>` : null,
-    { name: "fade" }
-  ),
-  "#app"
-);
-
-// Animate on first render too
-transition(html`<header>App</header>`, { name: "slide-down", appear: true });
-
-// JS hooks
-transition(content, {
-  name: "fade",
-  onBeforeEnter: (el) => el.setAttribute("aria-hidden", "false"),
-  onAfterLeave:  (el) => el.setAttribute("aria-hidden", "true"),
-});
-```
-
-### Dependency injection
-
-```typescript
-import { provide, inject, createInjectionKey } from "@deijose/nix-js";
-
-const ThemeKey = createInjectionKey<string>("theme");
-
-// Parent component
-function App() {
-  provide(ThemeKey, "dark");
-  return html`${ThemedCard()}`;
-}
-
-// Child component
-function ThemedCard() {
-  const theme = inject(ThemeKey); // "dark"
-  return html`<div class="card-${theme}">...</div>`;
-}
-```
+| Category | APIs |
+|---|---|
+| **Reactivity** | `signal`, `computed`, `effect`, `batch`, `watch`, `untrack`, `nextTick` |
+| **Templates** | `` html` ` ``, `repeat`, `ref`, `portal`, `transition`, `showWhen` |
+| **Components** | `NixComponent`, `mount`, lifecycle hooks, children & named slots |
+| **Router** | `createRouter`, `RouterView`, `Link`, `useRouter`, guards, nested routes |
+| **Forms** | `useField`, `createForm`, built-in validators, Zod/Valibot interop |
+| **State** | `createStore`, `provide`, `inject`, `createInjectionKey` |
+| **Async** | `suspend`, `lazy` |
+| **Error handling** | `createErrorBoundary` |
 
 ## Documentation
 
-For the complete API reference, guides, and all features (async/lazy, lifecycle hooks, event modifiers, keyed lists, query params, nested routes, and more):
+Full API reference, guides, and examples:
 
-**→ [Full documentation on GitHub](https://github.com/DeijoseDevelop/nix-js)**
+**→ [github.com/DeijoseDevelop/nix-js](https://github.com/DeijoseDevelop/nix-js)**
 
 ## License
 

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

@@ -1,68 +1,22 @@
 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.
-     */
+    /** Template shown while the promise is pending. */
     fallback?: NixTemplate;
-    /**
-     * Factory que recibe el error y devuelve el template de error.
-     * Por defecto: mensaje de error en rojo.
-     */
+    /** Factory receiving the error, returns the error template. */
     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.
-     */
+    /** If `true`, shows fallback during re-fetches instead of stale content. */
     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>`,
- *   }
- * )
+ * Runs an async function and renders based on its state (pending/resolved/error).
+ * Equivalent to the Suspense pattern in other frameworks.
  */
 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>`) },
- * ])
+ * Wraps a dynamic import for lazy-loading route components.
+ * The module is loaded once (cached). Compatible with `RouteRecord.component`.
+ * The imported module must use a default export.
  */
 export declare function lazy(importFn: () => Promise<{
     default: new () => NixComponent;

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

@@ -1,61 +1,27 @@
-/**
- * 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");
- */
+/** Typed key for provide/inject. Generic `T` enforces type safety between provider and consumer. */
 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())
- */
+/** Creates a unique typed InjectionKey. */
 export declare function createInjectionKey<T>(description?: string): InjectionKey<T>;
-/** @internal — devuelve copia del stack (para capturar en closures de efectos). */
+/** @internal — returns a copy of the stack for capturing in effect closures. */
 export declare function _captureContextSnapshot(): Map<unknown, unknown>[];
-/** @internal — push de un contexto vacío para un nuevo componente (render estático). */
+/** @internal — pushes an empty context for a new component (static render). */
 export declare function _pushComponentContext(): void;
-/** @internal — pop del contexto del componente actual (render estático). */
+/** @internal — pops the current component context (static render). */
 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()`).
+ * @internal — executes `fn` with `parentSnapshot` as ancestors and a fresh
+ * empty context on top, then restores the previous stack.
  */
 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()}`; }
- *   }
+ * Registers a value so descendant components can retrieve it via `inject()`.
+ * Must be called inside `onInit()` of a NixComponent.
  */
 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>`;
- *     }
- *   }
+ * Retrieves a value provided by an ancestor component.
+ * Searches child-to-parent; returns `undefined` if the key was not provided.
  */
 export declare function inject<T>(key: InjectionKey<T> | string | symbol): T | undefined;

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

@@ -8,54 +8,9 @@ export declare function pattern(regex: RegExp, message?: string): Validator<stri
 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")]);
- * ```
- */
+/** Creates a typed custom validator compatible with `useField` and `createForm`. */
 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)],
- *     },
- *   }
- * );
- * ```
- */
+/** All built-in validators grouped as a namespace. Extensible via `extendValidators`. */
 export declare const validators: {
     readonly required: typeof required;
     readonly minLength: typeof minLength;
@@ -68,48 +23,8 @@ export declare const validators: {
 /** 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.
+ * Merges custom validator factories into the built-in namespace.
+ * Returns a new object — the original is never mutated.
  */
 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. */
@@ -137,21 +52,7 @@ export interface FieldState<T> {
      */
     _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}
- * `
- */
+/** Creates a standalone reactive form field with optional validators. */
 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>> = {
@@ -229,30 +130,6 @@ export interface FormOptions<T extends Record<string, unknown>> {
 }
 /**
  * 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>
- * `
+ * schema-level validation (Zod/Valibot/Yup/custom), and submit handling.
  */
 export declare function createForm<T extends Record<string, unknown>>(initialValues: T, options?: FormOptions<T>): FormState<T>;