@deijose/nix-js 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deijose/nix-js",
+  "version": "0.1.0",
+  "description": "A lightweight, fully reactive micro-framework — no virtual DOM, no compiler, just signals and tagged templates.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "reactive",
+    "signals",
+    "micro-framework",
+    "ui",
+    "dom",
+    "typescript",
+    "no-vdom",
+    "frontend"
+  ],
+
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/lib/index.d.ts",
+        "default": "./dist/lib/nix-js.js"
+      },
+      "require": {
+        "types": "./dist/lib/index.d.ts",
+        "default": "./dist/lib/nix-js.cjs"
+      }
+    }
+  },
+  "main":   "./dist/lib/nix-js.cjs",
+  "module": "./dist/lib/nix-js.js",
+  "types":  "./dist/lib/index.d.ts",
+
+  "files": [
+    "dist/lib",
+    "!dist/lib/*.map",
+    "src/nix",
+    "src/index.ts"
+  ],
+
+  "sideEffects": false,
+
+  "engines": {
+    "node": ">=18.0.0"
+  },
+
+  "scripts": {
+    "dev":       "vite",
+    "build":     "tsc && vite build",
+    "preview":   "vite preview",
+    "build:lib": "vite build --config vite.lib.config.ts && tsc --project tsconfig.lib.json",
+    "typecheck": "tsc --noEmit"
+  },
+
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vite": "^8.0.0-beta.13"
+  },
+  "overrides": {
+    "vite": "^8.0.0-beta.13"
+  }
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// ❄️ Nix.js — Public Library Entry Point
+//
+// This file is the single entry point for the compiled library.
+// Import from here when using Nix.js as an installed package:
+//
+//   import { signal, html, NixComponent, mount } from "nix-js";
+
+// ── Values ────────────────────────────────────────────────────────────────────
+export {
+    // Reactivity
+    Signal,
+    signal,
+    effect,
+    computed,
+    batch,
+    watch,
+    untrack,
+    nextTick,
+    // Templates
+    html,
+    repeat,
+    ref,
+    // Components
+    mount,
+    NixComponent,
+    // Store
+    createStore,
+    // Router
+    createRouter,
+    RouterView,
+    Link,
+    useRouter,
+    // Async / Lazy
+    suspend,
+    lazy,
+    // Dependency Injection
+    provide,
+    inject,
+    createInjectionKey,
+} from "./nix";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+export type {
+    // Reactivity
+    WatchOptions,
+    // Templates
+    NixTemplate,
+    NixMountHandle,
+    KeyedList,
+    NixRef,
+    // Store
+    Store,
+    StoreSignals,
+    // Router
+    Router,
+    RouteRecord,
+    // Async
+    SuspenseOptions,
+    // Dependency Injection
+    InjectionKey,
+} from "./nix";

package/src/nix/async.ts

@@ -0,0 +1,164 @@
+// src/nix/async.ts — Fase 8: Lazy loading + Suspense
+
+import { signal } from "./reactivity";
+import { NixComponent } from "./lifecycle";
+import type { NixTemplate } from "./template";
+import { html } from "./template";
+
+// ── Tipos públicos ────────────────────────────────────────────────────────────
+
+type AsyncState<T> =
+    | { status: "pending" }
+    | { status: "resolved"; data: T }
+    | { status: "error"; error: unknown };
+
+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;
+}
+
+// ── suspend() ─────────────────────────────────────────────────────────────────
+
+/**
+ * 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 function suspend<T>(
+    asyncFn: () => Promise<T>,
+    renderFn: (data: T) => NixTemplate | NixComponent,
+    options: SuspenseOptions = {}
+): NixComponent {
+    const {
+        fallback,
+        errorFallback,
+        resetOnRefresh = false,
+    } = options;
+
+    const defaultFallback = fallback ?? html`
+        <span style="color:#52525b;font-size:13px;display:inline-flex;align-items:center;gap:6px">
+            <span class="nix-spinner" style="
+                display:inline-block;width:14px;height:14px;border-radius:50%;
+                border:2px solid #38bdf840;border-top-color:#38bdf8;
+                animation:nix-spin .7s linear infinite
+            "></span>
+            Cargando…
+        </span>
+        <style>@keyframes nix-spin{to{transform:rotate(360deg)}}</style>
+    `;
+
+    const defaultErrorFallback = errorFallback ?? ((err: unknown) => html`
+        <span style="color:#f87171;font-size:13px">
+            ⚠ ${err instanceof Error ? err.message : String(err)}
+        </span>
+    `);
+
+    class SuspendComponent extends NixComponent {
+        private _state = signal<AsyncState<T>>({ status: "pending" });
+
+        onMount(): void {
+            this._run();
+        }
+
+        private _run(): void {
+            if (resetOnRefresh || this._state.value.status === "pending") {
+                this._state.value = { status: "pending" };
+            }
+            asyncFn().then(
+                (data) => { this._state.value = { status: "resolved", data }; },
+                (err) => { this._state.value = { status: "error", error: err }; }
+            );
+        }
+
+        render(): NixTemplate {
+            return html`<div class="nix-suspense" style="display:contents">${() => {
+                const s = this._state.value;
+                if (s.status === "pending") return defaultFallback;
+                if (s.status === "error") return defaultErrorFallback(s.error);
+                return renderFn(s.data);
+            }}</div>`;
+        }
+    }
+
+    return new SuspendComponent();
+}
+
+// ── lazy() ────────────────────────────────────────────────────────────────────
+
+/**
+ * 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 function lazy(
+    importFn: () => Promise<{ default: new () => NixComponent }>,
+    fallback?: NixTemplate
+): () => NixComponent {
+    // Cache del constructor — null mientras no se haya cargado
+    let Cached: (new () => NixComponent) | null = null;
+
+    return (): NixComponent => {
+        // Si ya está cargado, instanciar directamente (sin Suspense)
+        if (Cached) return new Cached();
+
+        // Primera vez: cargar el chunk y cachear
+        return suspend(
+            async () => {
+                const mod = await importFn();
+                Cached = mod.default;
+                return Cached;
+            },
+            (Comp) => new Comp(),
+            { fallback }
+        );
+    };
+}

package/src/nix/component.ts

@@ -0,0 +1,76 @@
+// ═══════════════════════════════════════════════
+//  Nix.js ❄️ — Componentes  (Fase 3)
+// ═══════════════════════════════════════════════
+//
+//  Un componente en Nix.js es una función simple:
+//
+//    function MyComponent(props) {
+//      const count = signal(0);
+//      return html`<button @click=${() => count.update(n => n+1)}>
+//                    ${() => count.value}
+//                  </button>`;
+//    }
+//
+//  No hay clases, no hay decoradores, no hay registro.
+//  Las actualizaciones ocurren via signals — la función
+//  se ejecuta UNA sola vez.
+//
+//  mount(template, container) — monta la app raíz en el DOM.
+
+import type { NixTemplate, NixMountHandle } from "./template";
+import { isNixComponent, type NixComponent } from "./lifecycle";
+import { _pushComponentContext, _popComponentContext } from "./context";
+
+/**
+ * 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 function mount(
+    component: NixTemplate | NixComponent,
+    container: Element | string
+): NixMountHandle {
+    if (isNixComponent(component)) {
+        const el =
+            typeof container === "string"
+                ? (document.querySelector(container) as Element)
+                : container;
+        if (!el) {
+            throw new Error(`[Nix] mount: contenedor no encontrado: ${container}`);
+        }
+
+        _pushComponentContext();
+        let cleanup: () => void;
+        try {
+            try { component.onInit?.(); } catch (e) { if (component.onError) component.onError(e); else throw e; }
+            cleanup = component.render()._render(el, null);
+        } finally {
+            _popComponentContext();
+        }
+        let mountCleanup: (() => void) | undefined;
+
+        try {
+            const ret = component.onMount?.();
+            if (typeof ret === "function") mountCleanup = ret;
+        } catch (e) {
+            if (component.onError) component.onError(e);
+            else throw e;
+        }
+
+        return {
+            unmount() {
+                try { component.onUnmount?.(); } catch { /* ignore */ }
+                try { mountCleanup?.(); } catch { /* ignore */ }
+                cleanup();
+            },
+        };
+    }
+
+    // NixTemplate: delegar al método .mount() interno
+    return (component as NixTemplate).mount(container);
+}

package/src/nix/context.ts

@@ -0,0 +1,142 @@
+// ═══════════════════════════════════════════════
+//  Nix.js ❄️ — Provide / Inject  (Fase 13)
+// ═══════════════════════════════════════════════
+//
+//  Inyección de dependencias sin prop drilling:
+//
+//    Proveedor:
+//      class ThemeProvider extends NixComponent {
+//        theme = signal("dark");
+//        onInit() { provide(THEME_KEY, this.theme); }
+//        render()  { return html`...`; }
+//      }
+//
+//    Consumidor (cualquier nivel de profundidad):
+//      class Button extends NixComponent {
+//        theme = inject(THEME_KEY);   // Signal<string> | undefined
+//        render() {
+//          return html`<button class=${() => this.theme?.value}>OK</button>`;
+//        }
+//      }
+//
+//  Cómo funciona:
+//    Cada componente tiene su propio mapa de valores provistos.
+//    Al renderizar, el motor apila los mapas padre → hijo.
+//    inject() busca desde el tope de la pila hacia la raíz.
+
+// ─── Tipos públicos ───────────────────────────────────────────────────────────
+
+/**
+ * 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 function createInjectionKey<T>(description?: string): InjectionKey<T> {
+    return Symbol(description) as InjectionKey<T>;
+}
+
+// ─── Stack interno ────────────────────────────────────────────────────────────
+
+/** Pila de mapas provide, uno por componente activo en el árbol de render. */
+const _stack: Map<unknown, unknown>[] = [];
+
+/** @internal — devuelve copia del stack (para capturar en closures de efectos). */
+export function _captureContextSnapshot(): Map<unknown, unknown>[] {
+    return [..._stack];
+}
+
+/** @internal — push de un contexto vacío para un nuevo componente (render estático). */
+export function _pushComponentContext(): void {
+    _stack.push(new Map());
+}
+
+/** @internal — pop del contexto del componente actual (render estático). */
+export function _popComponentContext(): void {
+    _stack.pop();
+}
+
+/**
+ * @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 function _withComponentContext<T>(
+    parentSnapshot: Map<unknown, unknown>[],
+    fn: () => T
+): T {
+    const saved = _stack.splice(0);
+    parentSnapshot.forEach(m => _stack.push(m));
+    _stack.push(new Map()); // contexto propio, vacío al principio
+    try {
+        return fn();
+    } finally {
+        _stack.splice(0);
+        saved.forEach(m => _stack.push(m));
+    }
+}
+
+// ─── API pública ──────────────────────────────────────────────────────────────
+
+/**
+ * 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 function provide<T>(
+    key: InjectionKey<T> | string | symbol,
+    value: T
+): void {
+    const top = _stack[_stack.length - 1];
+    if (!top) {
+        throw new Error(
+            "[Nix] provide() debe llamarse dentro de onInit() de un NixComponent."
+        );
+    }
+    top.set(key, value);
+}
+
+/**
+ * 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 function inject<T>(
+    key: InjectionKey<T> | string | symbol
+): T | undefined {
+    for (let i = _stack.length - 1; i >= 0; i--) {
+        if (_stack[i].has(key)) {
+            return _stack[i].get(key) as T;
+        }
+    }
+    return undefined;
+}

package/src/nix/index.ts

@@ -0,0 +1,14 @@
+export { Signal, signal, effect, computed, batch, watch, untrack, nextTick } from "./reactivity";
+export type { WatchOptions } from "./reactivity";
+export { html, repeat, ref } from "./template";
+export type { NixTemplate, NixMountHandle, KeyedList, NixRef } from "./template";
+export { mount } from "./component";
+export { NixComponent } from "./lifecycle";
+export { createStore } from "./store";
+export type { Store, StoreSignals } from "./store";
+export { createRouter, RouterView, Link, useRouter } from "./router";
+export type { Router, RouteRecord } from "./router";
+export { suspend, lazy } from "./async";
+export type { SuspenseOptions } from "./async";
+export { provide, inject, createInjectionKey } from "./context";
+export type { InjectionKey } from "./context";

package/src/nix/lifecycle.ts

@@ -0,0 +1,112 @@
+// ═══════════════════════════════════════════════
+//  Nix.js ❄️ — Lifecycle Hooks  (Fase 4)
+// ═══════════════════════════════════════════════
+//
+//  Orden de ejecución garantizado:
+//
+//    new MyComponent()   ← constructor (opcional)
+//          ↓
+//    onInit()            ← sin DOM, síncrono, antes de render()
+//          ↓
+//    render()            ← retorna NixTemplate
+//          ↓
+//    [DOM insertado]
+//          ↓
+//    onMount()           ← con DOM; puede retornar cleanup
+//          ↓
+//    ...signals actualizan efectos internos...
+//          ↓
+//    onUnmount()         ← DOM aún presente
+//    cleanup de onMount()
+//          ↓
+//    [DOM removido]
+//
+//  onError(err)  → captura errores de onInit y onMount.
+
+import type { NixTemplate } from "./template";
+
+// ─── NixComponent ─────────────────────────────────────────────────────────────
+
+/**
+ * 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 abstract class NixComponent {
+    /** @internal – marca que identifica instancias NixComponent en el engine. */
+    readonly __isNixComponent = true as const;
+
+    /**
+     * 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;
+}
+
+// ─── Helper de tipo ───────────────────────────────────────────────────────────
+
+/**
+ * @internal – Verifica si un valor es una instancia de NixComponent.
+ */
+export function isNixComponent(v: unknown): v is NixComponent {
+    return (
+        v != null &&
+        typeof v === "object" &&
+        (v as Record<string, unknown>).__isNixComponent === true
+    );
+}