Loading...

Proporciona un ecosistema modular orientado al desacoplamiento de interfaces mediante la inyección asíncrona y coordinada de recursos HTML, CSS y JS. El sistema gestiona automáticamente el ciclo de vida de los componentes, la resolución de dependencias declarativas en el DOM, la mitigación de colisiones de IDs y flujos de degradación fluida ante fallos de carga o de red.

Librería: estructura.components.js

Dependencia obligatoria: estructura.http.js (HTTP, documentación). El objeto global _http debe estar disponible en el entorno antes de inicializar cualquier componente; de lo contrario, el proceso se interrumpirá emitiendo una excepción en consola.

1. Inicialización y Retorno de API

La biblioteca expone una interfaz funcional unificada. Al invocar _components, el valor de retorno varía según los parámetros proporcionados:

• Configuración global: Si se pasa un objeto plano, se actualizan las opciones de inicialización y se expone el método .config() para recuperar las opciones activas.
• Inicialización de elementos: Si se pasa un nodo del DOM, se inicia el ciclo del componente o coordinador y se expone el método .ref() para recuperar su instancia de control de ciclo de vida.

Configuración global del entorno:

// Definición de parámetros globales
var configActiva = _components({
       	origin: './src/components/',   // Ruta base para localizar recursos estáticos
	timeout: 10000,         // Límite de tiempo máximo para las peticiones (10s)
	autoScan: false         // Desactiva el escaneo automático del DOM al arrancar
}).config();

Inicialización y captura de referencia manual:

var contenedor = document.querySelector('#ficha_usuario');

// Montaje directo capturando la instancia de control
var componente = _components(contenedor, {
	component: 'perfil-cliente',
	id: 'tarjeta_activa'
}).ref();

2. Atributos Declarativos en el DOM

La declaración y relación de componentes se estructura semánticamente en el HTML mediante atributos específicos.

Atributos para Componentes Individuales (data-e-component-*)

• data-e-component (String): Directorio o nombre físico del componente a cargar bajo la ruta origen.
• 
  data-e-component-id (String): Identificador unívoco en el registro. En caso de colisión con un ID existente, el motor lo renombrará secuencialmente (ej. id_1) emitiendo una advertencia en la consola. Nota: Los mensajes enviados explícitamente al ID colisionado original no serán redirigidos a las instancias renombradas secundarias.
• 
  data-e-component-src (String): Sobrescribe la ruta origen global exclusivamente para esta instancia.
• 
  data-e-component-order (String): Secuencia específica de descarga de recursos del componente (por defecto: "css,html,js").
• 
  data-e-component-required (String): IDs de componentes cuya inicialización exitosa es requisito obligatorio antes de iniciar la carga de este elemento. Admite valores delimitados por comas, espacios o saltos de línea.
• 
  data-e-component-fallback (String): Componente alternativo de contingencia que se cargará si ocurre un error crítico en el flujo principal.
• 
  data-e-component-fallback-src (String): Origen de direccionamiento alternativo para el componente de contingencia.
• 
  data-e-component-fallback-order (String): Secuencia de carga de recursos asignada al flujo de contingencia.
• 
  data-e-component-timeout (Number): Límite de tiempo de carga específico para esta instancia.

Atributos para Coordinadores (data-e-components-*)

• data-e-components (Boolean/String): Establece que el nodo actuará como un coordinador jerárquico para sincronizar a sus descendientes.
• 
  data-e-components-origin (String): Ruta base de direccionamiento unificada para todos los componentes descendientes directos.
• 
  data-e-components-order (String): Cadena que prescribe el ordenamiento de carga secuencial y paralelo de los subcomponentes.
• 
  data-e-components-fallback-origin (String): Ruta de contingencia unificada aplicable a todos los componentes alternativos descendientes directos.
• 
  data-e-components-fallback-order (String): Estructura predeterminada del orden de contingencia aplicable a los subcomponentes del contenedor.

Búsqueda Recursiva Ascendente de Atributos: Si un componente individual que inicia un flujo de contingencia no declara de forma explícita sus orígenes de fallback (data-e-component-fallback-src), el motor ascenderá de manera recursiva por el árbol DOM buscando en los nodos padres los atributos del coordinador (data-e-components-fallback-origin) para heredar el direccionamiento.

Comportamiento Híbrido: Si un único nodo contiene los atributos data-e-component y data-e-components, se ejecutará una carga en cascada: primero se montará el componente individual y, una vez que alcance el estado listo ("ready"), se iniciará automáticamente el coordinador para procesar los subcomponentes anidados en su interior.

3. Orquestación y Flujos de Carga

Los coordinadores permiten estructurar la sincronización de carga de elementos secundarios mediante operadores lógicos en sus atributos de secuencia (order):

• Operador coma (,): Establece una secuencia obligatoria de pasos en cascada (esperar a que el bloque previo esté listo antes de arrancar la inicialización del siguiente).
• Operador suma (+): Indica concurrencia. Los elementos definidos se descargarán e inyectarán en paralelo dentro del mismo intervalo temporal.

Ejemplo de orquestación estructurada:

<!-- Inicializa 'estructura-base' y 'menu-lateral' al mismo tiempo. Una vez listos ambos, procede a inyectar 'panel-de-control' -->
<div data-e-components="mi_dashboard" data-e-components-order="estructura-base+menu-lateral, panel-de-control">
	<div data-e-component="estructura-base"></div>
	<aside data-e-component="menu-lateral" data-e-component-id="menu_izq"></aside>
	<article data-e-component="panel-de-control" data-e-component-required="menu_izq"></article>
</div>

4. Ciclo de Vida y Estados de Instancia

Las instancias recuperadas mediante .ref() exponen las siguientes propiedades y métodos de control:

• id (String): El identificador final único asignado a la instancia en el registro global.
• 
  element (HTMLElement): Referencia al elemento físico del DOM asociado.
• 
  options (Object): Configuración activa resuelta para la instancia actual.
• 
  status(): Retorna el estado actual de la instancia. Los estados posibles son:
  • "pending": Creado, esperando su turno de ejecución en la orquestación o resolución de componentes requeridos.
  • "loading": Realizando peticiones HTTP activas de CSS, HTML o JS. El DOM del elemento aún no se ha modificado.
  • "loading-fallback": Error detectado en la carga principal; inicializando el componente alternativo de contingencia.
  • "ready": Recursos descargados, inyectados y scripts ejecutados con éxito.
  • "failed": Error irrecuperable en el ciclo de carga del componente o de sus dependencias críticas.
• 
  _destroy(isReset): Ejecuta de manera ordenada la desconexión de observadores, la remoción de oyentes de eventos y la baja del componente en el registro global. El parámetro opcional isReset indica si la limpieza procede de una purga total de caché para mitigar advertencias de descarte sobre nodos aún conectados al DOM.

Suscripción a Eventos de Instancia

Cada instancia dispone de un emisor de eventos para añadir oyentes utilizando los métodos estándar on(), once() y off():

var inst = _components.get('panel-de-control');

if (inst) {
	// Notificación de ciclo completado de manera exitosa
	inst.on('ready', function() {
		console.log('Componente inyectado y funcional en el DOM.');
	});

	// Captura errores de red, timeouts o excepciones en la ejecución del JS inyectado
	inst.on('error', function(err) {
		console.error('Fallo en el ciclo del componente:', err.message);
	});
}

Mecanismo de Retención de Eventos (Cola de Mensajería):

Para asegurar la entrega de mensajes asíncronos enviados mediante _components.emit(), el motor retiene temporalmente los eventos en una cola interna hasta un límite estricto de 50 registros (MAX_QUEUE_SIZE). Si el componente destino alcanza el estado "ready", la cola se vacía cronológicamente y los eventos son despachados de forma síncrona. Si el componente destino transiciona al estado "failed", los eventos en cola se descartan de forma inmediata para proteger el uso de memoria de la aplicación.

5. Métodos de Control Global

La biblioteca expone utilidades globales en el objeto _components para coordinar el entorno desde flujos externos:

• _components.get(id): Obtiene la instancia activa registrada de un componente por su ID.
• 
  _components.emit(targetId, event, data): Envía eventos de manera segura a componentes específicos, gestionando colas de espera de forma transparente.
• 
  _components.order(name, value?): Registra o recupera alias de flujos de carga preestablecidos. Al registrar un nuevo valor, se purga de manera automática la caché interna relacionada.
• 
  _components.scan(root?): Escanea el subárbol del DOM provisto (o el documento entero por defecto) inicializando componentes y coordinadores declarados.
• 
  _components.autoScan(): Añade escuchadores automáticos para ejecutar el escaneo una vez que la estructura del documento esté lista.
• 
  _components.resetCache(): Libera memoria. Destruye de forma controlada todas las instancias del registro global, remueve observadores, restablece las cachés de red y purga las estructuras de orquestación cargadas.

Observador de Estado de Componentes:

Permite interceptar de manera global las transiciones de estado de todas las instancias creadas en el entorno, facilitando tareas de telemetría o el desarrollo de barras de carga globales:

function monitorDeEstados(id, nuevoEstado) {
	console.log('[Ciclo de Vida] Componente "' + id + '" pasó al estado: ' + nuevoEstado);
}

// Registro en el canal global de la extensión
_components._registerStateObserver(monitorDeEstados);

// Si se requiere dar de baja:
// _components._unregisterStateObserver(monitorDeEstados);

6. Arquitectura Interna y Características Técnicas