🌿 mita-dom

mita-dom es una librería reactiva moderna, modular e inclusiva, construida puramente sobre Vanilla JavaScript y Web Components nativos.

📖 El Origen del Nombre

El nombre de nuestro proyecto encierra un doble y poderoso significado cultural:

• Mitay (del Quechua): Refiere al sistema de "turnos de trabajo" optimizado en el Potosí colonial. En mita-dom, esto representa el motor interno de nuestro sistema reactivo (Signals), el cual gestiona y despacha las actualizaciones del DOM por turnos precisos y granulares, logrando la máxima eficiencia sin sobrecargar el procesador.
• Mita (del Guaraní): Significa "niño", "nuevo" o "nacimiento". Simboliza el renacer de la Web Nativa; una arquitectura fresca que devuelve a los desarrolladores a los fundamentos de la web, libres del peso de corporaciones y frameworks pesados.

🚀 ¿Qué hemos construido?

mita-dom es una librería de nivel Enterprise con Cero Dependencias. No utilizamos paquetes de terceros; de hecho, nuestra suite de pruebas está construida íntegramente sobre el estándar nativo de Node.js (node:test), sin requerir librerías externas pesadas como Vitest o Jest.

Ofrece un ecosistema completo para Single Page Applications (SPAs) enfocándose en el rendimiento absoluto:

• ⚛️ Reactividad Granular (Signals): Eliminamos el pesado Virtual DOM. Mutamos solo el texto necesario (.textContent) con precisión quirúrgica, optimizando el uso de CPU y batería.
• 🧭 Router SPA Nativo: Navegación ultra rápida e interceptada usando el estándar moderno Navigation API.
• 📦 Componentes Modulares: Web Components aislados y seguros utilizando CSS nativo (@scope), con un enfoque estricto en Mobile First y HTML Semántico.
• ⚡ Fetch Reactivo: Gestión limpia y asíncrona de recursos (loading, data, error) con excelente Experiencia del Desarrollador (DX).

⚙️ Arquitectura y Roadmap (Estado del Proyecto)

Actualmente, mita-dom es Production Ready para crear:

• ✅ SPA (Single Page Applications)
• ✅ Componentes Web Aislados (Microfrontends)
• ✅ Dashboards con Estado Global

🚧 En Construcción (Futuro Roadmap):

• ⏳ SSR (Server-Side Rendering): MitaDOM actualmente opera al 100% en el cliente.
• ⏳ SSG (Static Site Generation): Renderizado estático en tiempo de build.
• ⏳ Arquitecturas Híbridas & PWA: Soporte nativo para Service Workers y Offline-First.

---

📚 Ecosistema de Documentación y Ruta de Aprendizaje

Para dominar MitaDOM, te recomendamos leer la documentación en este orden:

📖 Conceptos Base

1. Filosofía y Misión: ¿Por qué creamos MitaDOM? ¿Qué problemas resuelve?
2. Fundamentos Web y Git: Lo que debes saber sobre REST, Git, SPA y el DOM para no depender de frameworks.
3. Fundamentos Reactivos: Aprende sobre Signals y Granular DOM sin VDOM.
4. Arquitectura Core: Polyfills, Memory Leaks, SEO y Seguridad.

🧩 Componentes y UI

5. Guía Maestra de Componentes: Los 4 pilares de Web Components en MitaDOM.
6. Web Components Nativos (Props): Cómo usar observedAttributes y propiedades nativas de clase en vez de directivas mágicas.
7. Renderizado Condicional: Alternativas de Vanilla JS a v-if, v-show y visibility.
8. Teleport y Portales: Patrones avanzados de comunicación entre componentes distantes.

🌐 Ecosistema y Datos

9. Enrutamiento SPA Avanzado: La Navigation API moderna frente a History API, rutas dinámicas y Catch-All 404.
10. Datos, APIs y LocalDB: Fetch asíncrono, persistencia nativa con IndexedDB y Storage Adapter.
11. Ecosistema Vite y HMR: Hot Module Replacement sin recargas y configuración de SPA.
12. Testing y UI: Node:test para core, Vitest para componentes y Mita Profiler para 60FPS.

🛠️ Práctica y Casos de Uso

13. Ejemplos Prácticos (Learn MitaDOM): ¿Vienes de React o Vue? Mira cómo hacer listas y toggles.
14. Patrones Avanzados: Arquitectura de Persistencia, y Guards.

---

⚙️ Inicio Rápido y Uso

🚨 Guía de Migración a v2.x (Breaking Changes)

Si vienes de la versión 1.x, debes tener en cuenta los siguientes cambios arquitectónicos introducidos en la v2.1.6:

1. Eliminación de estadoAppGlobal: El core del framework ya no exporta estados globales prefabricados. Ahora tú debes crear tus propias instancias en tu aplicación utilizando las factorías de Experiencia del Desarrollador (DX): const miEstado = crearEstadoGlobal(0). Nota: la clase base new Signal(0) sigue siendo totalmente soportada como la primitiva de bajo nivel para compatibilidad hacia atrás.
2. Nueva API CRUD para Signals: Las mutaciones directas (estado.value = 10) han sido deprecadas. Ahora debes usar .get(), .set(), .update(), .patch() y .reset().
3. Persistencia y Arquitectura Avanzada: El constructor de Signal ahora acepta un objeto de opciones para Inmutabilidad y Adaptadores de Bases de Datos (storageAdapter).
4. Mita Vite Plugin: Se incluyó mitaHmrPlugin() para facilitar el Granular HMR en tus proyectos de Vite.

---

1. Iniciar un proyecto nuevo (Automatizado)

Si quieres empezar un proyecto nuevo con todo configurado automáticamente (Servidor local, Bundler, y TypeScript opcional), te recomendamos usar el andamiaje oficial de Vite:

# Para crear un proyecto en Vanilla JS puro:
npm create vite@latest mi-proyecto -- --template vanilla

# O si prefieres TypeScript (Configurará tsconfig.json y entorno automáticamente):
npm create vite@latest mi-proyecto -- --template vanilla-ts

2. Instalar mita-dom

Entra a la carpeta de tu proyecto e instala nuestra librería:

cd mi-proyecto
npm install mita-dom

3. Actualizar a la Última Versión

Dado que iteramos constantemente con nuevas mejoras de rendimiento, si ya tenías instalada la librería en un proyecto antiguo y deseas actualizarla a la última versión (ej. migrar a la v2.2.x), simplemente ejecuta:

npm install mita-dom@latest

3. Uso Básico

mita-dom es modular, solo importas lo que necesitas. Aquí un ejemplo rápido usando Signals y el Router:

import { crearEstadoGlobal, rutaActual, navegarA } from 'mita-dom';

// Crear estado global con telemetría automática, persistencia e inmutabilidad
const estadoGlobal = crearEstadoGlobal({ contador: 0 }, { 
  immutable: true,
  persistKey: 'mi_app_estado'
});

// Mutación parcial avanzada (v2.x)
estadoGlobal.patch({ contador: 1 });
rutaActual.suscribir((ruta) => {
    console.log("El usuario navegó de manera fluida a:", ruta);
});

💙 Compatibilidad Total con TypeScript

mita-dom está escrita en Vanilla JS, pero incluye nativamente sus archivos de declaración (.d.ts). ¡No necesitas instalar paquetes @types/mita-dom extra!

Si usas TypeScript en tu proyecto, disfrutarás de autocompletado estricto y soporte para genéricos de inmediato:

import { crearEstadoLocal, crearRecurso } from 'mita-dom';

// TypeScript inferirá estrictamente que este estado solo acepta números
const contador = crearEstadoLocal<number>(0);

// Forzará errores en tiempo de compilación si intentas algo inválido:
// contador.set("hola"); // ❌ Error TS: Type 'string' is not assignable to type 'number'

3. Ejemplos y Entorno de Desarrollo

Para probar la librería en un entorno real y visualizar componentes, consulta nuestros proyectos de ejemplo separados:

• example-mita-spa-01-js: Aplicación de ejemplo usando Vite + Vanilla JS + mita-dom.

Warning

No utilices npm run preview dentro de este repositorio. mita-dom es una librería, no una SPA. El comando preview de Vite devolverá un error 404 porque no genera un index.html en la compilación. Para probar mita-dom, instálalo en un proyecto externo.

4. Pruebas Automáticas

Mantenemos la librería ligera usando los test-runners nativos de Node.js v24:

node --test

🌍 Inclusividad Tecnológica

De Bolivia para el mundo. mita-dom es nuestra respuesta social a la sobrecomplejidad de la industria actual. Al no depender de pesadas librerías de terceros, construimos aplicaciones extremadamente ligeras y veloces que cargan al instante.

Esto permite que personas con dispositivos móviles de gama baja o conexiones a internet limitadas puedan acceder a la información sin barreras, logrando una verdadera inclusión digital.

---

mita-dom te devuelve el control y la comprensión profunda de la Web.

• 📚 Lee nuestra visión y filosofía técnica en el MANIFIESTO.md.
• 🛠️ Aprende a mejorar o actualizar la librería en nuestra Guía de Mantenimiento.