@deijose/nix-js 1.0.6 → 1.0.8

package/README.md

@@ -1,322 +1,105 @@
-# ❄️ 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, NixTemplate, NixComponent, mount, createRouter, RouterView, Link, useRouter } from "@deijose/nix-js";
 
-function Counter() {
-  const count = signal(0);
+// --- Pages as function components (NixTemplate) ---
+// Plain functions returning html`` are recommended for pages and
+// display-only components — no class needed, signals just work.
 
+function HomePage(): NixTemplate {
+  const count = signal(0);
   return html`
-    <div>
-      <h1>${() => count.value}</h1>
-      <button @click=${() => count.value++}>Increment</button>
-    </div>
+    <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
+function UserPage(): NixTemplate {
+  const router = useRouter();
+  return html`<h1>User: ${() => router.params.value.id}</h1>`;
+}
 
-```typescript
-import { NixComponent, mount, html } from "@deijose/nix-js";
-import { signal } from "@deijose/nix-js";
+// --- Stateful component as class component (NixComponent) ---
+// Use a class when you need lifecycle hooks: onInit / onMount / onUnmount.
 
-class MyComponent extends NixComponent {
-  private msg = signal("Hello");
+class Clock extends NixComponent {
+  private time = signal(new Date().toLocaleTimeString());
+  private _id = 0;
 
-  onInit() {
-    setTimeout(() => (this.msg.value = "World"), 1000);
+  onMount() {
+    this._id = setInterval(() => {
+      this.time.value = new Date().toLocaleTimeString();
+    }, 1000);
+    return () => clearInterval(this._id); // auto-cleanup on unmount
   }
 
   render() {
-    return html`<p>${() => this.msg.value}</p>`;
+    return html`<p>Clock: ${() => this.time.value}</p>`;
   }
 }
 
-mount(MyComponent, document.body);
-```
-
-### Stores
-
-```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 ---
 
-### Router
-
-```typescript
-import { createRouter, RouterView, Link, html } from "@deijose/nix-js";
-
-const router = createRouter([
-  { path: "/",       component: Home },
-  { path: "/about",  component: About },
+createRouter([
+  { path: "/",         component: () => HomePage() },
+  { path: "/user/:id", component: () => 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";
+// --- App shell (function component) ---
 
-class Card 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>
-    `;
-  }
+function App(): NixTemplate {
+  return html`
+    <nav>${new Link("/", "Home")} ${new Link("/user/42", "User 42")}</nav>
+    ${new Clock()}
+    ${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(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** | `NixTemplate` (function components), `NixComponent` (lifecycle class), `mount`, 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/component.d.ts

@@ -1,13 +1,13 @@
 import type { NixTemplate, NixMountHandle } from "./template";
 import { type NixComponent } from "./lifecycle";
 /**
- * Monta un NixTemplate o NixComponent en el DOM.
+ * Mounts a NixTemplate or NixComponent into the DOM.
  *
- *   mount(App(), "#app");           // NixTemplate (función componente)
- *   mount(new Timer(), "#app");     // NixComponent (clase con lifecycle)
+ *   mount(Counter(), "#app");   // NixTemplate (function component)
+ *   mount(new Timer(), "#app"); // NixComponent (class with 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.
+ * @param component NixTemplate (result of html``) or a NixComponent instance.
+ * @param container CSS selector or HTMLElement to mount into.
+ * @returns         { unmount() } — disposes effects and removes DOM.
  */
 export declare function mount(component: NixTemplate | NixComponent, container: Element | string): NixMountHandle;

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;