hp3-dom

Utilidades DOM modernas y livianas basadas en SelectArray, una microclase que permite manipulación fluida del DOM con una API encadenable.

Parte del ecosistema hp3, hp3-dom proporciona funciones para crear y seleccionar elementos del DOM de forma sencilla y coherente.

🚀 Instalación

npm install hp3-dom

📦 Uso rápido

import {select, create} from "hp3-dom";

// Crear un nuevo botón
const btn = create("button", {
    id: "my-btn",
    className: "btn",
    style: {backgroundColor: "tomato", color: "white"},
    disabled: false,
    textContent: "Haz clic",
});

// Insertarlo en el body
btn.appendTo(document.body);

// Seleccionar por CSS
const botones = select(".btn");

// Agregar eventos o modificar elementos encadenadamente
botones
    .on("click", () => alert("¡Haz hecho clic!"))
    .attr("data-clickable", "true");

📚 API Doc

📌 Constantes

La librería no presenta constantes

🧩 Clases

class SelectArray : Array<Element>

Clase que extiende de Array y proporciona una interfaz rica para manipular elementos del DOM. Permite trabajar con múltiples elementos simultáneamente, similar a jQuery, pero manteniendo la estructura moderna de JavaScript.

constructor(elements?): SelectArray

Crea una nueva instancia de SelectArray a partir de diversos tipos de entradas.

Si no se proporciona elements, o se proporciona un tipo no válido, la colección se inicializa vacía.

Parámetros

• elements?: (Element | NodeList | SelectArray | Array<Element>)
  • Element: crea una instancia con un solo elemento.
  • NodeList: crea una instancia que contiene todos los elementos de la lista.
  • SelectArray: crea una instancia que contiene todos los elementos de la lista, equivalente a .clone()
  • Array: crea una instancia que contiene únicamente los objetos de tipo Element contenidos en el array.

Retorna

• SelectArray: La nueva instancia creada.

Ejemplos

// Desde un único elemento
const item = new SelectArray(document.querySelector("div"));

// Desde un NodeList
const items = new SelectArray(document.querySelectorAll("li"));

// Desde otra instancia
const itemsCopy = new SelectArray(items);

// Desde un array de elementos
const divs = new SelectArray([document.body, document.createElement("div")]);

// Instancia vacía
const empty = new SelectArray();

Propiedades

Se heredan de Array.

Métodos

addClass(...args): SelectArray

Agrega una o más clases CSS a todos los elementos de la colección.

Este método acepta clases de varias formas:

• Como múltiples argumentos separados: addClass('foo', 'bar')
• Como un solo string con espacios: addClass('foo bar')
• Como un array de strings: addClass(['foo', 'bar'])
• Como un array que contenga strings con espacios: addClass(['foo bar', 'baz'])

Las clases vacías o inválidas se filtran automáticamente.

Parámetros

• ...args: ...(string | string[]): Clases CSS a agregar, ya sea como strings individuales, string con espacios o arrays.

Retorna

• SelectArray: La instancia actual para encadenamiento.

Ejemplo

// Agregar una sola clase
select("p").addClass("resaltado");

// Agregar varias clases.
select("div").addClass("activo visible sombreado"); // Válido.
select("section").addClass("columna", "centrado", "oscuro"); // Válido.
select(".card").addClass(["borde", "sombra"]); // Válido.
select(".item").addClass([["rojo", "grande"], "activo"]); // Válido.

// Evita clases vacías o inválidas.
select("span").addClass("", null, undefined, "valido"); // Solo se aplicará "valido"

append(...args): SelectArray

Agrega contenido dinámicamente como hijo del primer elemento de la colección SelectArray. Este método permite insertar texto, nodos DOM, fragmentos de documento, funciones generadoras de nodos o incluso otras instancias de SelectArray Este método acepta múltiples tipos de valores:

Restricción: Solo opera si la colección contiene exactamente un elemento. Si hay más de uno o ninguno, no realiza cambios y retorna la colección sin modificar.

Entrada flexible: Acepta múltiples tipos de argumentos y los interpreta adecuadamente según su tipo.

Nota Adicional: Si se pasa un solo argumento, y este es un array, se desempaqueta y se trata como múltiples argumentos.

Parámetros

• ...args: ...(string | number | function | Node | Object): elementos que se agregarán como hijos.
  • string | number: Se convierten en nodos de texto con document.createTextNode.
  • function: Se invoca con el elemento destino y el índice del argumento como parámetros. Se espera que retorne un nodo válido a insertar.
  • Element o DocumentFragment: Se inserta directamente como hijo.
  • SelectArray: Se itera sobre sus elementos internos y se insertan uno a uno.

Retorna

• SelectArray: La instancia que llama a append (permite encadenamiento).

Ejemplos

select("#contenedor").append("Hola mundo");
select("#contenedor").append(document.createElement("span"));
select("#contenedor").append([document.createTextNode("Uno"), "Dos"]);

appendTo(element): SelectArray

Inserta todos los nodos contenidos en la instancia actual de SelectArray como hijos de un elemento de destino mediante appendChild.

Comportamiento Detallado

Este método transfiere cada nodo de la colección actual hacia el interior del nodo destino especificado.

La operación preserva el orden de los nodos dentro del SelectArray.

Si el destino es una instancia de SelectArray, se asegura que contenga exactamente un solo elemento, y en ese caso extrae dicho nodo para proceder.

⚠️ Como appendChild mueve nodos del DOM en lugar de clonarlos, si el SelectArray ya contiene nodos que están en otro lugar del documento, estos se reubicarán.

Parámetros

• element: (Element | SelectArray): El nodo DOM donde se desea insertar el contenido. Si es una instancia de SelectArray, debe contener exactamente un nodo.

Retorna

• SelectArray: La instancia que llama a appendTo (permite encadenamiento).

Ejemplo

const span = document.createElement('span');
span.textContent = 'Hola';

const sa = new SelectArray([span]);
sa.appendTo(document.body); // Inserta el <span> en el <body>

// Alternativamente con create():
create("span").text("Hola").appendTo(document.body);

attr(p, v?): (string | Array<string> | SelectArray | undefined)

Método versátil para obtener, establecer o eliminar atributos HTML en los elementos de la colección.

• Si se pasa un nombre de atributo (p) como cadena y no se proporciona valor (v), se obtiene el valor del atributo:
  • Si la colección tiene un solo elemento, se retorna el valor como una cadena.
  • Si la colección tiene múltiples elementos, se retorna un arreglo con los valores del atributo (p).
  • Si el atributo no existe retorna undefined.
• Si se pasa un nombre de atributo (p) y un valor (v), se asigna ese valor al atributo en todos los elementos.
• Si se pasa un objeto (p), se asignan múltiples atributos por cada par clave/valor del objeto.
• Admite pasar funciones como valor (v) para establecer atributos dinámicamente.

Parámetros

• p: (string | Object.<string, *>): nombre del atributo a obtener/establecer, o un objeto con pares atributo/valor.
  • string: en nombre del atributo.
  • Object.<string, *>: el objeto que se interpreta como múltiples atributos por cada par clave/valor.
    • *: equivalente a v.
• v?: (function | *): el valor de asignación del atributo.
  • function: función que retorna el valor del atributo que se desea asignar. Se pasan los parámetros v(element, attr, i).
  • *: valor del atributo (se pasa como string).

Retorna

• undefined: en modo lectura, si el atributo no existe.
• string: en modo lectura, si la colección tiene un elemento y el atributo existe.
• Array<string>: en modo lectura, si el atributo existe.
• SelectArray: en modo escritura, la misma instancia de SelectArray para permitir encadenamiento de métodos.

Ejemplo

select("img").attr("src"); // Devuelve el 'src' de la imagen si hay un solo elemento, o un array si hay varios elementos.

select("a").attr("href", "https://example.com"); // Asigna el mismo href a todos los elementos seleccionados.

select("input").attr({ // Establecer múltiples atributos.
    type: "text",
    placeholder: "Escribe algo"
});

select("li").attr("data-index", (el, attr, i) => i); // Asigna el índice como data-index a cada <li>.

select("div").attr({ // Usar función para establecer múltiples atributos.
    "data-width": el => el.offsetWidth,
    "data-height": el => el.offsetHeight
});

select("input").attr("disabled", undefined); // Elimina el atributo "disabled".

children(selector?): SelectArray

Devuelve los elementos hijos del primer nodo de la colección, opcionalmente filtrados por un selector.

Parámetros

• selector?: string: Selector CSS opcional para filtrar los hijos.

Retorna

• SelectArray: Colección de elementos hijos (filtrados si se proporciona un selector).

Ejemplo

const container = select('#container');

// Obtener todos los hijos
const allChildren = container.children();

// Obtener solo los hijos con clase `.card`
const cards = container.children('.card');

// Aplicar estilos a los hijos visibles
container.children('.visible').style({ opacity: '1' });

clear(): SelectArray

Limpia el contenido HTML (innerHTML) de todos los elementos.

Retorna

• SelectArray: La instancia actual para encadenamiento.

Ejemplo

// Limpiar el contenido de un único elemento.
select("#mensaje").clear();

// Limpiar múltiples elementos a la vez.
select(".contenedor").clear();

// Usado en combinación con otros métodos encadenados.
select("ul.lista").clear().addClass("vacia");

// Antes de inyectar nuevo contenido.
select("#panel").clear().append(create("div").text("Contenido actualizado"));

// Vaciar todos los elementos.
select("article").clear();

clone()

Crea una copia superficial de la instancia actual de SelectArray.

Esta función retorna una nueva instancia de SelectArray que contiene los mismos elementos que la instancia original, manteniendo la referencia a los mismos nodos DOM.

Retorna

• SelectArray: una nueva instancia con los mismos elementos.

Ejemplo

const items = select(".item");
const copia = items.clone();
// `copia` contiene los mismos elementos que `items`, pero como una nueva instancia de SelectArray.

data(p, v): (string | Array<string> | SelectArray | undefined)

Obtiene, asigna o elimina atributos data-* a los elementos DOM de la colección utilizando la propiedad dataset.

Comportamientos admitidos:

• Modo Lectura:

  • Si p es una cadena y no se proporciona v, se obtienen los valores del atributo data-* correspondiente:
    • Si la colección tiene un solo elemento, se devuelve una cadena.
    • Si la colección tiene múltiples elementos, se devuelve un array de cadenas.

• Modo Escritura:

  • Si p es una cadena y v está definido, se asigna v al atributo data-* en todos los elementos.
  • Si p es un objeto, se asignan múltiples atributos data-* utilizando los pares clave/valor del objeto.
  • Si el valor de una clave es undefined, se elimina el atributo correspondiente.
  • También se aceptan funciones como valor (v) para asignación dinámica. Estas funciones reciben el elemento, nombre de atributo y el índice como argumentos function(el, data, i).

Parámetros

• p: (string | Object.<string, *>): nombre del atributo a obtener/establecer, o un objeto con pares atributo/valor.
  • string: en nombre del atributo.
  • Object.<string, *>: el objeto que se interpreta como múltiples atributos por cada par clave/valor.
    • *: equivalente a v.
• v?: (function | * | undefined): el valor de asignación del atributo.
  • Si no se proporciona entra en modo lectura.
  • undefined: elimina el dataset.
  • function: función que retorna el valor del atributo que se desea asignar. Se pasan los parámetros v(element, attr, i).
  • *: valor del atributo (se pasa como string).

Retorna

• undefined: en modo lectura, si el dataset no existe.
• string: en modo lectura, si la colección tiene un elemento y el dataset existe.
• Array<string | undefined>: en modo lectura, si la colección tiene más de un elemento:
  • string: si el datasetexiste.
  • undefined: si el dataset no existe.
• SelectArray: en modo escritura, la misma instancia de SelectArray para permitir encadenamiento de métodos.

Ejemplo

// Leer un dataset foo [data-foo]
select('.item').data('foo'); // "bar"

// Asignar un valor
select('.item').data('foo', 'bar');

// Asignar múltiples dataset [data-foo="bar" data-index="2"]
select('.item').data({foo: 'bar', index: 2});

// Asignación dinámica con función
select('.item').data('foo', (el, key, i) => i % 2 ? 'odd' : 'even');

// Eliminar un dataset pasando undefined (elimina [data-foo]).
select('.item').data('foo', undefined);

deepClone(recursive = true): SelectArray

Crea una copia de todos los elementos de la colección y retorna una nueva instancia de SelectArray.

Permite realizar una clonación superficial o profunda dependiendo del valor del parámetro recursive.

Si se establece una clonación recursiva, este método clona cada nodo de forma recursiva, incluyendo sus hijos, atributos y contenido, y retorna una nueva instancia de SelectArray con los nodos clonados.

A diferencia del método clone(), que solo copia referencias a los elementos existentes, deepClone() genera nuevos nodos DOM completamente independientes.

Parámetros

• recursive?: indica si se realiza una copia recursiva de los nodos o no.
  • true: se clonan también todos los nodos hijos (clonación profunda).
  • false: se clona solo el nodo raíz.

Ejemplo

const items = select(".item");

// Clonación superficial
const copiaShallow = items.deepClone(false);

// Clonación profunda
const copiaDeep = items.deepClone(true);

each(callback): SelectArray

Itera sobre cada elemento de la colección y ejecuta una función callback.

El callback recibe como argumentos:

• Una instancia de SelectArray conteniendo el elemento actual.
• El índice del elemento dentro de la colección.

Este método permite ejecutar lógica personalizada sobre cada elemento, manteniendo el estilo funcional y encadenable.

Parámetros

• callback: Función que recibe una sub-colección y su índice.

Retorna

• SelectArray: Colección original tras iterar.

Ejemplo

// Iterar para cambiar texto en cada elemento.
select('.item').each((el, i) => {
    el.text(`Elemento número ${i + 1}`);
});

// Añadir una clase condicional.
select('.item').each((el, i) => {
    if (i % 2 === 0) {
        el.addClass('par');
    } else {
        el.addClass('impar');
    }
});

// Agregar un atributo data-index personalizado.
select('.item').each((el, i) => {
    el.data('index', i);
});

// Remover elementos vacíos.
select('.item').each((el) => {
    if (el.text().trim() === '') {
        el.remove();
    }
});

// Aplicar estilos directos.
select('.box').each((el, i) => {
    el.style("backgroundColor", i % 2 ? 'lightblue' : 'lightgray');
});

first(): SelectArray

Devuelve una nueva colección SelectArray con el primer nodo de la colección actual.

Si la colección está vacía, se retorna una instancia vacía de SelectArray.

Retorna

• SelectArray: Una nueva instancia de SelectArray con el primer nodo, o una instancia vacía si no hay elementos.

Ejemplo

// Agrega una clase solo al primero
select('.item').first().addClass('highlight');

// Usar con colección vacía sin errores
const vacio = select('.no-existe'); // Devuelve un SelectArray vacío
const primero = vacio.first();      // Sigue siendo un SelectArray vacío
console.log(primero.length);        // 0

html(value?)

Obtiene o establece el contenido HTML (innerHTML) de los elementos de la colección.

• Lectura (sin argumentos):

  • Si la colección está vacía, devuelve undefined.
  • Si contiene un solo elemento, devuelve su contenido como string.
  • Si contiene múltiples elementos, devuelve un Array<string> con el HTML de cada uno.

• Escritura (con argumento value):

  • Si value es un string, lo asigna directamente como innerHTML.
  • Si value es una function, se llama con (element, index) y su resultado se asigna como HTML.
  • Otros tipos de valor serán ignorados para mayor seguridad.

Parámetros

• value?: Valor a establecer, o función generadora de HTML.
  • Si se omite entra en modo lectura.
  • string: valor a establecer.
  • function(Element, number): string: función generadora de HTML.

Retorna

• string: en modo lectura, el HTML del primer elemento si la colección tiene solo un elemento.
• string[]: en modo lectura, un array con el contenido HTML de todos los elementos de la colección.
• undefined en modo lectura, si no hay elementos.
• SelectArray: en modo escritura, si se escribe (para encadenamiento).

Ejemplo

// Leer HTML de un solo elemento.
const title = select('#main-title').html();

// Leer HTML de múltiples elementos.
const items = select('.list-item').html();
// Supongamos que hay 3 elementos con .list-item
// items = ["<li>Item 1</li>", "<li>Item 2</li>", "<li>Item 3</li>"]

// Establecer HTML de todos los elementos.
select('.message').html('<strong>Actualizado</strong>');

// Asignar HTML dinámicamente con una función.
select('.item').html((el, i) => `<span>Item ${i + 1}</span>`);

isEmpty(): boolean

Verifica si la colección no contiene elementos DOM.

Retorna

• boolean: true si la colección está vacía, false en caso contrario.

Ejemplo

// Verificar si una selección no contiene elementos.
if (select('.no-existe').isEmpty()) {
    console.log('No se encontró ningún elemento con la clase .no-existe');
}

// Evitar operaciones innecesarias.
const items = select('.item');

if (!items.isEmpty()) {
    items.addClass('activo');
}

// Uso combinado con operadores ternarios.
const mensaje = select('#alert').isEmpty()
    ? 'No hay alerta activa.'
    : 'Alerta mostrada en pantalla.';
console.log(mensaje);

item(index = 0): SelectArray

Devuelve una nueva colección SelectArray que contiene el nodo en la posición especificada.

Si el índice está fuera del rango válido, se retorna una instancia vacía de SelectArray.

Parámetros

• index: number: Índice del nodo a seleccionar (basado en cero).

Retorna

• SelectArray: Una nueva instancia de SelectArray con el nodo en la posición dada, o una instancia vacía si el índice no es válido.

Ejemplo

// Obtener el primer elemento de la colección.
select('button').item().addClass('highlighted');

// Obtener un elemento específico por índice.
const secondParagraph = select('p').item(1);
if (!secondParagraph.isEmpty()) {
    console.log('Segundo párrafo:', secondParagraph.html());
}

// Ejemplo con índices negativos.
const imgs = select('img');

imgs.item(-1).addClass('last-image');    // Última imagen
imgs.item(-2).addClass('second-last');   // Penúltima imagen
imgs.item(-imgs.length).addClass('first'); // Equivalente a item(0)

// Iterar manualmente por índices.
const items = select('.item');
for (let i = 0; i < items.length; i++) {
    const el = items.item(i);
    el.addClass(`item-${i}`);
}

// Manejo seguro si el índice está fuera de rango.
const links = select('a');
const maybeMissing = links.item(100); // Si no hay tantos <a>, retorna un SelectArray vacío

if (maybeMissing.isEmpty()) {
    console.log('El enlace no existe.');
}

// Encadenamiento con otros métodos.
select('.card')
    .item(2)
    .addClass('selected')
    .html('<strong>Elemento activo</strong>');

last(): SelectArray

Devuelve una nueva colección SelectArray con el último nodo de la colección actual.

Si la colección está vacía, se retorna una instancia vacía de SelectArray.

Retorna

• SelectArray: Una nueva instancia de SelectArray con el último nodo, o una instancia vacía si no hay elementos.

Ejemplo

// Seleccionar y modificar el último elemento.
select('p').last().addClass('final-paragraph');

// Obtener el HTML del último elemento.
const lastHtml = select('.item').last().html();
console.log(lastHtml);

// Aplicar estilos solo al último elemento.
select('.box').last().style({border: '2px solid red'});

// Eliminar el último hijo de un contenedor
select('.container *').last().remove();

node(index = 0): (Element | undefined)

Obtiene el nodo en la posición especificada dentro de la colección.

• El índice puede ser negativo para contar desde el final de la colección. Por ejemplo, -1 devuelve el último elemento, -2 el penúltimo, etc.
• Si el índice está fuera de rango, se retorna undefined.

Parámetros

• index: number: Índice del nodo a retornar. Soporta valores negativos.

Retorna

• Element: el elemento DOM en la posición indicada.
• undefined: si la colección está vacía o el índice es inválido.

Ejemplo

const boxes = select('.box');

// Obtener el primer elemento (por defecto).
console.log(boxes.node().textContent);

// Obtener el segundo elemento.
console.log(boxes.node(1).textContent);

// Usar índice negativo para acceder al último elemento.
console.log(boxes.node(-1).textContent);

// indices no válidos retorna `undefined`.
console.log(boxes.node(500)); // undefined
console.log(boxes.node(-500)); // undefined
console.log(boxes.node(new Object())); // undefined

on(type, selectorOrCallback, callbackOrOptions, options): SelectArray

Agrega un manejador de eventos a todos los elementos de la colección.

Soporta eventos directos y delegados:

• Si se proporciona un selector, se usa delegación de eventos.
• Si no se proporciona un selector, se agrega directamente al elemento.

Parámetros

• type: string: Tipo de evento (por ejemplo, 'click', 'input', etc.).
• selectorOrCallback: (string | Function): Selector CSS para delegación o directamente el callback si no se usa delegación.
• callbackOrOptions? : (Function | Object): Función callback a ejecutar o un objeto options si no hay selector.
• options? : (Object | boolean): Opciones del listener (capture, once, passive, etc.), o useCapture: boolean.

Retorna

• SelectArray: La instancia actual para encadenamiento.

Ejemplo

// Evento directo:
select('button').on('click', (e) => {
    console.log('Clic directo en:', e.currentTarget);
});

// Evento delegado:
select('ul').on('click', 'li', (e) => {
    console.log('Item clickeado:', e.currentTarget);
});

// Evento con opción `once`:
select('button').on('click', (e) => {
    console.log('Este mensaje se muestra solo una vez.');
}, {once: true});

parent(): SelectArray | undefined

Obtiene el elemento padre del primer elemento de la colección.

Si no hay elementos o el primero no tiene padre, se retorna undefined.

Retorna

• SelectArray: Instancia de SelectArray con el elemento padre.
• undefined: Si no existe elemento padre.

Ejemplo

const hijo = select('.item');
const padre = hijo.parent();

if (padre) {
  padre.addClass('tiene-hijo-seleccionado');
}

parents(): SelectArray

Obtiene los elementos padre de todos los elementos de la colección, sin duplicados.

Retorna

• SelectArray: Colección de elementos padre únicos.

Ejemplo

const children = select('.child');
const parents = children.parents();

parents.addClass('highlight');

prop(p, v): (* | Array<*> | SelectArray | undefined)

Obtiene o establece propiedades nativas en los elementos DOM de la colección.

• Si se proporciona una cadena (p) sin valor (v), se obtiene el valor de la propiedad:
  • Si la colección tiene un solo elemento, retorna el valor directamente.
  • Si tiene múltiples elementos, retorna un arreglo con los valores.
• Si se proporciona una cadena (p) y un valor (v), se asigna ese valor como propiedad a todos los elementos.
• Si se proporciona un objeto (p), se asignan múltiples propiedades por cada par clave/valor del objeto.

Parámetros

• p: (string | Object.<string, *>): Nombre de la propiedad a obtener/establecer, o un objeto con pares propiedad/valor.
• v?: *: Valor a asignar a la propiedad si p es una cadena.

Retorna

• * | Array<*>: El valor de la propiedad si se obtiene (como valor simple o arreglo),
• undefined: Si la colección está vacía y se intenta obtener una propiedad.
• SelectArray: La instancia actual para encadenamiento.

Ejemplo

// 1.- Lectura de propiedades.
// Obtener el valor de la propiedad 'checked' de un checkbox.
const isChecked = select('input[type="checkbox"]').prop('checked');

// Obtener los valores 'disabled' de múltiples elementos.
const disabledStates = select('button').prop('disabled');
console.log(disabledStates); // → [false, true, false]

// 2.- Escritura de una sola propiedad.
// Deshabilitar todos los botones.
select('button').prop('disabled', true);

// Establecer el valor de un input de texto.
select('input[name="email"]').prop('value', '[email protected]');

// 3.- Asignación de múltiples propiedades .
// Establecer múltiples propiedades en una imagen.
select('img.logo').prop({
    alt: 'Logotipo de la empresa',
    src: '/images/logo.png'
});

// 4.- Escritura dinámica con función.
// Marcar como 'checked' solo los checkboxes en posiciones pares
select('input[type="checkbox"]').prop('checked', (el, i) => i % 2 === 0);

// 5.- Eliminar propiedad (estableciendo undefined explícitamente).
// Elimina la propiedad 'hidden' si estaba presente
$('.modal').prop('hidden', undefined);

remove(): SelectArray

Elimina del DOM todos los elementos de la colección.

Retorna

• SelectArray: Colección original, ahora sin los elementos en el DOM.

Ejemplo

// Elimina todos los elementos con clase "notificacion" del DOM.
select('.notificacion').remove();

// Elimina el elemento con id "modal".
select('#modal').remove();

// Elimina todos los elementos coincidentes con cualquiera de los selectores.
select('ul li.eliminar, .cerrar, .toast').remove();

// Elimina las filas con índice par.
select('.fila').each((el, i) => {
    if (i % 2 === 0) el.remove();
});

removeClass(...args): SelectArray

Elimina una o más clases CSS de todos los elementos de la colección.

Este método acepta clases en distintos formatos:

• Como múltiples argumentos: removeClass('foo', 'bar')
• Como un único string con espacios: removeClass('foo bar')
• Como un array de strings: removeClass(['foo', 'bar'])
• Como un array que contenga strings con espacios: removeClass(['foo bar', 'baz'])

Las clases vacías o inválidas se omiten automáticamente.

Parámetros

• args: ...(string | string[]): :Clases CSS a eliminar.

Retorna

• SelectArray: La instancia actual para encadenamiento.

Ejemplo

// Elimina la clase "activo" de todos los elementos con clase "caja".
select('.caja').removeClass('activo');

// Elimina "primario" y "resaltado" de todos los botones seleccionados.
select('.boton').removeClass('primario', 'resaltado');

// Elimina ambas clases de cada ".fila".
select('.fila').removeClass('seleccionada marcada');

// Misma funcionalidad, pero con un array explícito.
select('.tarjeta').removeClass(['activo', 'visible']);

// Elimina "rojo", "grande" y "parpadea" de cada elemento.
select('.elemento').removeClass(['rojo grande', 'parpadea']);

// Quita clases y añade otra en un solo encadenamiento.
select('#banner').removeClass('fijo oculto').addClass('desplegado');

replaceClass(oldClass, newClass): SelectArray

Reemplaza una clase CSS por otra en todos los elementos de la colección.

Este método solo realiza el reemplazo si ambos argumentos son strings no vacíos.

Parámetros

• oldClass: string: Clase CSS a reemplazar.
• newClass: string: Nueva clase CSS que reemplazará a la anterior.

Retorna

• SelectArray: La instancia actual para encadenamiento.

Ejemplo

// Reemplaza la clase "activo" con "inactivo" en todos los elementos ".tarjeta".
select('.tarjeta').replaceClass('activo', 'inactivo');

// Cambia "abierto" por "cerrado" y luego elimina "resaltado".
select('#menu').replaceClass('abierto', 'cerrado').removeClass('resaltado');

/// Asegurar que no se hace nada si las clases están vacías.
select('.elemento').replaceClass('', 'nuevo');    // No hace nada
select('.elemento').replaceClass('viejo', '');    // No hace nada

// Solo cambiará elementos que efectivamente tengan la clase "no-existe".
select('.fila').replaceClass('no-existe', 'agregado');

// Cambia "primario" por "secundario" en todos los botones seleccionados.
select('.boton').replaceClass('primario', 'secundario');

style(p, v): SelectArray

Obtiene o establece estilos en línea en los elementos DOM de la colección.

• Si se pasa un nombre de propiedad CSS (p) como cadena y no se proporciona valor (v), se obtiene el valor del estilo:
  • Si la colección tiene un solo elemento, se retorna el valor como una cadena.
  • Si la colección tiene múltiples elementos, se retorna un arreglo con los valores.
• Si se pasa un nombre de propiedad (p) y un valor (v), se asigna ese estilo en todos los elementos.
• Si se pasa un objeto (p), se asignan múltiples estilos en cada elemento usando los pares propiedad/valor del objeto.

Parámetros

• p: (string | Object.<string, string>):Nombre de la propiedad CSS a obtener/establecer, o un objeto con pares propiedad/valor.
• v?: *: Valor a asignar al estilo si p es una cadena.

Retorna

@returns {string | Array | SelectArray | null}

• string: El valor del estilo si se obtiene, y la colección tiene un solo elemento.
• Array<string>: El valor del estilo si se obtiene, y la colección tiene más de un elemento.
• null: Si la colección está vacía y se intenta obtener un valor,
• SelectArray: En modo escritura, para encadenamiento.

Ejemplo

// Obtener un estilo de un solo elemento.
select('#caja').style('backgroundColor'); // → "red" (por ejemplo)

// Obtener un estilo de múltiples elementos.
select('.item').style('display'); // → ["block", "none", "flex", ...]

// Establecer un solo estilo en todos los elementos.
select('.destacado').style('color', 'blue'); // Aplica color azul a todos los elementos con clase .destacado

// Establecer múltiples estilos con un objeto.
select('p').style({
    fontSize: '18px',
    lineHeight: '1.6',
    marginTop: '10px'
}); // Asigna varios estilos a todos los <p>

// Usar una función dinámica para asignar el valor.
select('.caja').style('width', (el, i) => `${100 + i * 10}px`); // Asigna un ancho progresivo a cada elemento .caja

// Sin efecto si la colección está vacía.
select('.no-existe').style('color'); // → null

text(value): SelectArray

Obtiene o establece el contenido textual (textContent) de los elementos DOM de la colección.

• Si no se proporciona ningún argumento, se obtiene el texto:
  • Si hay un solo elemento, se retorna como cadena.
  • Si hay múltiples, se retorna un arreglo de cadenas.
• Si se proporciona un valor, se asigna como textContent a todos los elementos.
  • El valor puede ser una cadena o una función que retorne una cadena.

Parámetros

• value?: (string | function): Texto a establecer o función que lo genera dinámicamente.

Retorna

• string | Array<string> | SelectArray | undefined:
  • string | Array<string>: El contenido textual si se lee (como cadena o arreglo).
  • undefined: Si la colección está vacía.
  • SelectArray: La instancia actual si se establece un valor, permite encadenamiento.

Ejemplo

// Si hay un solo elemento .item:
console.log(select('.item').text()); // → "Hola mundo"

// Si hay múltiples elementos .item:
console.log(select('.item').text()); // → ["Hola", "mundo", "!", ...]

// Establece "Título actualizado" como texto en todos los elementos con clase .title
select('.title').text('Título actualizado');

// Asigna "Elemento #1", "Elemento #2", etc., a cada <li>
select('li').text((el, i) => `Elemento #${i + 1}`);

// Leer texto cuando no hay elementos.
const empty = select('.no-existe');
console.log(empty.text()); // → undefined

toggleClass(...args): SelectArray

Alterna (añade o elimina) una o más clases CSS en todos los elementos de la colección.

Este método acepta clases en distintos formatos:

• Como múltiples argumentos: toggleClass('foo', 'bar')
• Como un único string con espacios: toggleClass('foo bar')
• Como un array de strings: toggleClass(['foo', 'bar'])
• Como un array que contenga strings con espacios: toggleClass(['foo bar', 'baz'])

Las clases vacías o inválidas se omiten automáticamente.

Parámetros

• args: ...(string | string[]): Clases CSS a alternar.
• force?: boolean: Si se proporciona, fuerza agregar (true) o eliminar (false) la clase.

Retorna

Ejemplo

// Si tiene la clase "activo", la quita. Si no, la agrega.
select('#menu').toggleClass('activo');

// Alterna ambas clases en cada botón
select('.btn').toggleClass('enabled', 'highlighted');

// Equivale a alternar 'selected' y 'focused'
select('div.card').toggleClass('selected focused');

// Alterna ambas clases
select('.box').toggleClass(['visible', 'expanded']);

// Alternar usando array que contiene strings con espacios.
select('.panel').toggleClass(['open closed', 'active']); // Equivale a ['open', 'closed', 'active']

// Se asegura de que todos los <li> tengan la clase 'marcado'
select('li').toggleClass('marcado', true);

// Se asegura de que todos los <li> NO tengan la clase 'marcado'
select('li').toggleClass('marcado', false);

// Usar dentro de un evento
select('.caja').on('click', function () {
    this.toggleClass('activo');
});

🛠️ Métodos

select(arg, [context])

Selecciona uno o más elementos del DOM y los encapsula en una instancia de SelectArray, que proporciona una API fluida para manipulación del DOM de manera encadenada.

Si el argumento no es válido, se retorna una instancia vacía de SelectArray.

Parámetros

• arg: (string | Element | NodeList | Array<Element>):
  • Selector CSS, un solo elemento, una NodeList o un array de elementos DOM.
• context? (Element | Document, opcional): Contexto sobre el cual aplicar el selector CSS. Solo se usa si arg es un string. Por defecto es document.

Retorna

SelectArray — Una instancia que contiene los elementos seleccionados.

Ejemplo

// Devuelve un SelectArray con todos los elementos que tengan la clase "btn"
const botones = select('.btn');

// Devuelve un SelectArray con todos los <li> dentro de #menu
const contenedor = document.querySelector('#menu');
const items = select('li', contenedor);

// Devuelve un SelectArray con ese único elemento
const elemento = document.getElementById('main');
const s = select(elemento);

// Devuelve un SelectArray con todos los <section>
const nodos = document.querySelectorAll('section');
const secciones = select(nodos);

// Devuelve un SelectArray con esos dos elementos
const e1 = document.createElement('div');
const e2 = document.createElement('span');
const lista = select([e1, e2]);

// Encadenar métodos del SelectArray
select('.alert')
    .addClass('visible')
    .style('color', 'red')
    .on('click', () => console.log('¡Click en alerta!'));

// Uso con valores inválidos.
const nada = select(123);     // => SelectArray vacío
const nada2 = select(null);   // => SelectArray vacío

create(tag, attrs?)

Crea un nuevo elemento del DOM con atributos opcionales y lo envuelve en una colección SelectArray.

Soporta:

• Atributos estándar como id, className, href, etc.
• Atributos booleanos como disabled, checked, etc., que solo se aplican si su valor es true.
• Estilos en formato objeto mediante la propiedad especial style, por ejemplo: { style: { color: "red" } }.

Cuando es posible, asigna atributos directamente como propiedades DOM para mejorar el rendimiento.

Parámetros

• tag (string): Nombre de la etiqueta HTML a crear (por ejemplo, 'div', 'span', 'input').
• attrs (Object, opcional): Atributos HTML a aplicar al elemento.
  La propiedad style puede ser un objeto con claves y valores CSS.
  También se admiten valores booleanos (por ejemplo, { disabled: true }).

Retorna

SelectArray — Instancia que contiene el nuevo elemento creado.

Ejemplo

// Crear un <div> vacío y lo añade al <body>.
create('div').appendTo(document.body);

// Crear un <button> con atributos estándar.
create('button', {
    id: 'my-btn',
    className: 'btn primary',
    textContent: 'Haz clic',
}).appendTo(document.body);

// Crear un <input> deshabilitado.
const input = create('input', {
    type: 'text',
    placeholder: 'Nombre',
    disabled: true
});
input.appendTo('#form');

// Crear un <a> con enlace y estilos en línea.
create('a', {
    href: 'https://ejemplo.com',
    target: '_blank',
    textContent: 'Ir al sitio',
    style: {
        color: 'blue',
        textDecoration: 'underline',
        fontWeight: 'bold'
    }
}).appendTo(document.body);

// Crear un <span> y añadirle clases y eventos.
create('span', {
    className: 'etiqueta',
    textContent: 'Etiqueta dinámica'
}).addClass('nueva-clase')
    .on('click', (e) => alert('¡Clic en el span!'))
    .appendTo(document.body);

// Crear un elemento y establecer atributos personalizados.
create('div', {
    'data-role': 'tarjeta',
    'aria-hidden': true,
    className: 'card'
}).appendTo('#contenedor');