cyan-air

v2.2.1

Published

2 months ago

Framework JS ligero para crear interfaces de datos y aplicaciones web basadas en componentes con diseño responsivo integrado.

0High
0Medium
0Low

pensadornatural

cyan-air vb6-style typescript

Cyan Air

Framework JS ligero para crear interfaces de datos y aplicaciones web basadas en componentes con diseño responsivo integrado.

🚀 Instalación y Uso

Opción 1: Vía CDN (Recomendado para uso directo en HTML)

Incorpora esta línea en la sección <head> de tu documento HTML:

<script src="https://unpkg.com/cyan-air/dist/cyan-air.js"></script>

Opción 2: Vía NPM (Para desarrollo con TypeScript/Node)

npm install cyan-air

🏗️ 1. Creación y Autoinstanciación de Componentes

En Cyan Air, un componente es un archivo .html que encapsula su estructura, estilo y lógica.

Al importar un componente, Cyan Air crea automáticamente un objeto global con el mismo nombre del archivo, brindándole métodos integrados.

Cómo nombrar archivos: puedes utilizar letras, números y guión bajo.

Ejemplo: `hola_mundo.html`

En este ejemplo, el componente parpadea cambiando su color mediante el método SetStyle() de Cyan Air (se verá a continuación). Se usa también la clase .box, que dibuja un borde de esquinas redondeadas:

<!-- CSS -->
<style>
    .center {
        text-align: center;
    }
</style>

<!-- HTML -->
<div class="box center">
    <h1 id="saludo">¡Hola mundo!</h1>
</div>

<!-- JavaScript -->
<script>
    // Ejemplo de lógica del componente: parpadeo cambiando el estilo con SetStyle.
    let esVisible = true;

    setInterval(() => {
        if (esVisible) {
            CyanAir.SetStyle("saludo", { Color: "transparent", Transition: "all 0.2s ease" });
        } else {
            CyanAir.SetStyle("saludo", { Color: "#000" });
        }
        
        esVisible = !esVisible;
    }, 200);
</script>

Importar este componente en `index.html`

<!DOCTYPE html>
<html lang="es">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />

        <!-- Cyan Air -->
        <script src="https://unpkg.com/cyan-air/dist/cyan-air.js"></script>
    </head>
    
    <body>
        <script>
            //Importación de componente "hola_mundo.html".
            CyanAir.Import('./hola_mundo.html');
        </script>
    </body>
</html>

Métodos automáticos de todo componente:

.Listen(idObjeto: string, message: string, metaMessage: any = ""): Método donde el componente escucha los mensajes que emitan otros componentes u objetos, y el lugar donde programar las reacciones a los mensajes que le interesen.
.Listening(escuchando: boolean = true): Define si el componente comienza la escucha de mensajes o la detiene.
.Talk(message: string, metaMessage: any = ""): Publica un mensaje que escuchan todos los objetos y componentes (los que estén escuchando).
.SetVisibility(activado: boolean = true): Muestra u oculta el componente, y el espacio asignado se mantiene.
.GetVisibility(): Devuelve true o false según si el componente está visible o no.
.SetDisplay(activado: boolean = true): Muestra u oculta el componente, incluyendo el espacio asignado.
.GetDisplay(): Devuelve true o false según si el componente y el espacio asignado están visibles o no.
.SetOpacity(activado: boolean = true): Muestra o hace transparente al componente, pero mantiene el espacio y la interactividad.
.GetOpacity(): Devuelve true o false según si el componente está transparente o no.
.Show(): Muestra el componente, independientemente de si se ocultó vía Display, Visibility u Opacity.
.SetEnabled(activado: boolean = true): Habilita/deshabilita el componente y sus elementos hijo. Deshabilitado, pierde toda interactividad.
.Delete(): Elimina el componente del DOM y de las listas de objetos de Cyan Air.

Como ejemplo, podría escribirse:

hola_mundo.SetEnabled(false);
hola_mundo.Delete();

🎨 2. Estilización Responsiva con `SetStyle`

Cyan Air elimina la dependencia de archivos CSS externos para el diseño adaptativo. Mediante el método SetStyle, puedes definir reglas visuales que cambian automáticamente según el tamaño de la pantalla, aplicándolas a cualquier ID, clase (debe incluirse el punto inicial en el nombre de la clase) o etiqueta global (body, h1, div, etc.).

Diseño Adaptativo en una línea

SetStyle permite pasar un objeto para Escritorio y otro para Móvil. El framework gestiona el evento resize de forma eficiente mediante un sistema de Debounce para no afectar el rendimiento.

// Configuración universal (afecta a todos los <body>)
CyanAir.SetStyle("body", 
    { BackgroundColor: "#F4F6F8", Padding: "40px", FontFamily: "Arial" }, // Desktop
    { BackgroundColor: "#FFFFFF", Padding: "10px" }                       // Mobile (< 768px)
);

// Configuración por ID
CyanAir.SetStyle("contenedor_principal", {
    Display: "flex",
    JustifyContent: "center",
    Gap: "20px",
    MarginTop: "5%"
});

✨ Características del motor de estilos

El motor de estilos de Cyan Air no es un simple inyector de CSS; está diseñado para ofrecer una experiencia de desarrollo fluida (DX) y un rendimiento optimizado.

Soporte CamelCase y PascalCase: Escribe tus propiedades como objetos nativos de JavaScript. El motor traduce automáticamente BackgroundColor o borderBottomRadius al formato que el navegador requiere.
Selectores Universales: No estás limitado a IDs. Puedes pasar etiquetas globales ("body", "h1"), selectores de clase (".card") o selectores complejos ("div > p").
Gestión Inteligente de Resize (Debounce): Para evitar caídas de frames (lag) al redimensionar la ventana, Cyan Air agrupa todas las peticiones de estilo y las aplica solo cuando el usuario ha terminado de mover la ventana.
Prioridad de Estilo Inline: Al aplicarse directamente sobre el elemento, estos estilos tienen mayor especificidad que las reglas de archivos CSS externos, permitiendo sobrescribir diseños base fácilmente.
Fallback Automático: Si no defines un objeto para dispositivos móviles, el framework utilizará automáticamente la configuración de escritorio, garantizando que el elemento nunca se quede sin diseño.
Inyección de Variables CSS: Soporte nativo para Custom Properties. Puedes pasar --mi-variable dentro del objeto y se aplicará mediante setProperty de forma transparente.

Comparativa de Sintaxis

Tip de rendimiento: Para animaciones fluidas, puedes combinar SetStyle con la propiedad Transition. Cyan Air aplicará el cambio y el navegador se encargará de la transición suave.

🌐 3. Conexión a Datos y APIs con `CreateDataService`

Cyan Air simplifica la comunicación con servidores externos mediante servicios de datos, objetos que pueden enviar peticiones HTTP y recibir respuestas de distintos endpoints a través de los métodos GET, PUT, POST y DELETE.

// Crea los servicios de datos con un nombre identificador
CyanAir.CreateDataService("ProductosVenta");

Y luego podrías traer productos de una API mediante:

ProductosVenta.GET(URLEndPoint);

Cuando termina la ejecución de los métodos de un servicio de datos, se ejecuta la función de evento _OnReady o _OnError, según si la operación fue exitosa o fallida:

function ProductosVenta_OnReady() {
    //Aquí, tu código que sigue después del éxito de la petición, como por ejemplo, actualizar un listado de productos.
}

function ProductosVenta_OnError() {
    //Aquí, tu código que sigue después de obtener un error en la petición, como por ejemplo, porque el usuario no está autorizado.
}

Los datos recibidos desde un endpoint quedan disponibles en la propiedad .Response, y el status en la propiedad .Status. Por ejemplo: ProductosVentas.GetResponse() devuelve los datos retornados por ProductosVenta.GET(URLEndPoint).

📟 4. `NavBar`

Crea una o más NavBar de manera simple, preparada nativamente para pantallas de escritorio y móviles.

CreateNavBar(id: string, targetId: string)

Este comando permite crear una NavBar, especificando un id y el id del contenedor del DOM en donde se renderizará. Puedes crear, por ejemplo, una NavBar en el Header y otra en el Footer, y cambiar los estilos CSS a cada una.

Para crear las opciones, usa:

CreateOption(id: string, text: string, url: string), donde id es el id de la opción, text es el texto que se muestra y url es la URL a donde dirige.

Ejemplo: se crea una NavBar llamada MainNavBar que se renderiza dentro del elemento del DOM de Id navbar, con 3 opciones, y luego se cambian los estilos mediante algunos de sus métodos, tanto para la versión de escritorio como para la versión móvil:

CyanAir.CreateNavBar('MainNavBar', 'navbar');
    MainNavBar.CreateOption("MainNavBarInicio", "Inicio", url1);
    MainNavBar.CreateOption("MainNavBarServicios", "Servicios", url2);
    MainNavBar.CreateOption("MainNavBarContacto", "Contacto", url3);

MainNavBar.SetTextColor("#fff");
MainNavBar.SetTextHoverColor('#007bff');
MainNavBar.SetMovilTextColor("#ccc");
MainNavBar.SetMovilBackgroundColor("#222");

📟 5. Feedback al Usuario: `StatusBar`

La StatusBar es un componente centralizado en Cyan Air diseñado para ofrecer comunicación visual inmediata al usuario. Permite mostrar estados de carga, confirmaciones de éxito o alertas de error sin interrumpir el flujo de la aplicación con ventanas emergentes (pop-ups).

Uso de la StatusBar

Puedes invocar la barra de estado desde cualquier parte de tu código (dentro o fuera de un componente) utilizando el método .SetCaption().

//Primero, crear la StatusBar.
CyanAir.CreateStatusBar();

//Si se fija SetAutoShow en true, la StatusBar se mantiene oculta y se muestra solamente por unos segundos cuando debe mostrar un mensaje.
CyanAir.StatusBar.SetAutoShow(true);

//Luego, envía los mensajes que necesites al usuario
CyanAir.StatusBar.SetCaption(TextoMensaje);

Es mejor lo siguiente: programar la barra de estado para que reaccione a los mensajes de un canal (por ejemplo, "usuario") ejecutando su propio método .SetCaption(). De este modo, la StatusBar mostrará cualquier mensaje que se publique en ese canal, pero manteniendo a componentes y objetos totalmente independientes, pues no es necesario que sepan siquiera de la existencia de la StatusBar. En este ejemplo, se diferencian los mensajes que tengan un metamensaje igual a "Success", "Unsuccess", "Notice" o "Warning", porque la StatusBar acepta un segundo parámetro opcional que hace que se coloree distinto para cada valor (se pueden cambiar con métodos como SetStatusBarSuccessColor(), SetStatusBarSuccessBackColor(), etc.).

function StatusBar_Listen(channel, idObjeto, mensaje, metaMensaje) {
    if (channel === "usuario") {
        if (metaMensaje === 'Success' || metaMensaje === 'Unsuccess' || metaMensaje === 'Warning' || metaMensaje === 'Notice') {
            CyanAir.StatusBar.SetCaption(mensaje, metaMensaje);
        } else {
            CyanAir.StatusBar.SetCaption(mensaje);
        }
    }
}

⚡ 6. Eventos Automáticos (Estilo VB6)

Una de las características más distintivas de Cyan Air es su sistema de eventos automáticos. Inspirado en la simplicidad de Visual Basic, el framework vincula automáticamente la lógica de JavaScript con los elementos del DOM basándose únicamente en sus IDs.

¿Cómo funciona?

No necesitas usar document.querySelector ni addEventListener. Si un elemento (como un botón o un input) tiene un id, Cyan Air buscará en el entorno global una función que siga el patrón: Id_Evento.

Eventos de Botones e Input (`_OnClick`, `_OnChange`, etc.)

Para cualquier botón o textbox (input de tipo text) con un ID definido, simplemente crea funciones con el sufijo _OnNombreEvento. Primero, registra el botón o textbox para que Cyan Air llame a sus funciones de eventos cuando el navegador los lance. Por ejemplo:

//En tu HTML, si tienes el botón <button id="btnGuardar">Guardar</button>
CyanAir.IsButton("btnGuardar");

// Esta función se ejecuta automáticamente al hacer clic
function btnGuardar_OnClick() {
    //Ahora el botón existe como objeto y puedes usar sus métodos, como por ejemplo, Enabled().
    btnGuardar.Enabled(false); 
}

function btnGuardar_OnChange() {
    //Tu código aquí...
}

En los botones, al hacer un IsButton(), también accedes a una característica muy útil: botones toggle. Puedes convertir un botón en un interruptor de estado con el método TuBoton.SetToggle(). Al hacer clic, el objeto recordará si está "encendido" o "apagado", facilitando lógicas de interfaz como mostrar/ocultar paneles. Para saber si está encendido o apagado, utiliza TuBoton.GetToggled(), que retorna un true o false, respectivamente.

En los textbox, los eventos permiten capturar las acciones del usuario en formularios de manera inmediata y limpia, facilitando procesos como la validación de datos o la actualización de cálculos en tiempo real. El evento _OnBlur se dispara automáticamente cuando el usuario deja de interactuar con un campo (hace clic fuera de él o presiona Tab). Es el lugar ideal para ejecutar validaciones de formato.

Cyan Air permite configurar fácilmente los textbox, y validar automáticamente los valores ingresados. Si la entrada del usuario es correcta, el marco se muestra en verde; si no, tanto porque ingresó algo incorrecto como si no ingresó nada y el campo es obligatorio, el marco se muestra en rojo. Por ejemplo:

// En el componente: <input type="text" id="txtEmail" placeholder="Tu correo">

CyanAir.IsTextBox("txtEmail");
txtEmail.SetMinLength(3);
txtEmail.SetMaxLength(70);
txtEmail.SetInputType(CyanAir.Const.Email); //Solo acepta valores de tipo email.
txtEmail.SetNeeded(true); //Indica que es obligatorio ingresar un correo.
txtEmail.SetCaption("3 a 70 letras, dígitos, subrayado o un @");

💡 Ventajas del sistema de eventos automáticos

El modelo de eventos de Cyan Air no solo reduce la cantidad de código, sino que cambia fundamentalmente la forma en que estructuras la lógica de tu aplicación.

Eliminación del "Boilerplate": Olvídate de escribir repetitivamente document.getElementById, addEventListener o el chequeo de DOMContentLoaded. El framework mapea las funciones directamente al ciclo de vida del DOM.
Referencia Global Inmediata: Al usar el sistema de eventos, el ID del elemento se convierte automáticamente en un objeto disponible en tu función. Puedes llamar a métodos como id_objeto.Enabled(false) o id_objeto.Visibility(true) sin buscar el elemento previamente.
Código Altamente Legible: Al ver una función llamada perfil_btnGuardar_OnClick, cualquier desarrollador sabe exactamente a qué elemento pertenece y qué acción la dispara. La lógica está "autodocumentada".
Desacoplamiento Estructural: Puedes mover elementos en tu HTML o cambiar su jerarquía; mientras conserven su ID, la lógica de negocio en JavaScript seguirá funcionando sin necesidad de actualizar selectores CSS complejos o rutas del DOM.
Mantenimiento Simplificado: Localizar un error es mucho más rápido. Si el botón de "Eliminar" falla, sabes que debes buscar la función btnEliminar_OnClick en el script del componente.
Curva de Aprendizaje Mínima: Al seguir un patrón predecible (Id_Evento), los desarrolladores nuevos en el proyecto pueden empezar a crear interactividad de inmediato sin dominar APIs complejas del navegador.

Nota: Cyan Air gestiona internamente la limpieza de memoria. Cuando un componente se destruye (con el método Delete()), el framework sabe qué eventos dejar de escuchar, optimizando el rendimiento general de la página.

📋 Lista de sufijos soportados

Cyan Air mapea los eventos nativos del navegador a un formato de nomenclatura predecible. Para que una función se vincule automáticamente, debe seguir la estructura ID_Sufijo.

Consideraciones importantes:

Prioridad Global: Las funciones de eventos deben estar declaradas en el ámbito global (fuera de otras funciones) para que Cyan Air pueda localizarlas y ejecutarlas.
Parámetros del Evento: Todas las funciones de evento reciben opcionalmente el objeto event nativo, por si necesitas acceder a propiedades específicas como coordenadas del mouse o teclas especiales:

   function btnMapa_OnClick(e) {
       console.log("Clic en coordenadas:", e.clientX, e.clientY);
   }

Soporte para Componentes: Aislamiento y Orden

Cuando utilizas CyanAir.Import(), el framework no solo carga el HTML, sino que realiza un escaneo inteligente del componente.

Ámbito del Componente: Los eventos definidos dentro de un archivo de componente (como mi_componente.html) se vinculan automáticamente al objeto global generado para ese componente.
Prevención de Conflictos: Aunque tengas dos componentes distintos con botones que se llamen igual (ej: btnGuardar), Cyan Air recomienda prefijar los IDs con el nombre del componente (ej: perfil_btnGuardar). Esto asegura que la función perfil_btnGuardar_OnClick sea única y no colisione con otras.
Carga Dinámica: Los eventos se registran en el mismo instante en que el componente termina de cargarse en el DOM, permitiendo que la interactividad esté disponible de inmediato sin recargar la página.

📊 7. Dashboards: Componentes de Visualización de Datos

Con Cyan Air puedes crear fácilmente tableros de control. Incluye una serie de objetos especializados para mostrar indicadores clave (KPIs) y gráficos de tendencia de forma nativa.

🗂️ KPI Cards (Tarjetas de Indicadores)

Las tarjetas de KPI permiten mostrar métricas críticas de un vistazo. Existen dos variantes según la complejidad requerida:

KpiCardBasic

Ideal para métricas simples. Muestra un título, un valor principal y una descripción. Para crear una, se debe especificar un nombre, el id del elemento del DOM que será el contenedor donde se renderizará, y un objeto con valores para uno o más de los parámetros: Value, Subtitle, Description, Width. También se pueden asignar posteriormente mediante los métodos .SetValue(), SetSubtitle(), etc.

En el siguiente ejemplo, se crea una tarjeta y se le asigna un tema (Light) para cambiar los colores por defecto. Hay muchos temas disponibles, como: Light, Forest, ForestDark, OceanModern, Sunset, entre otros.

CyanAir.CreateKpiCardBasic("KpiVentas", "IdContenedor", {Value: 54, Subtitle: "Ventas", Description: "Total de ventas del mes"});
KpiVentas.Theme("Light");

// Actualizar el valor dinámicamente
KpiVentas.SetValue("$14.200");

📈 KpiCard (Indicador con Tendencia)

La KpiCard es la evolución de la tarjeta básica. Está diseñada para mostrar no solo un dato puntual, sino su comportamiento respecto a un periodo anterior mediante un porcentaje y un icono de tendencia (flecha arriba/abajo). Para crear una tarjeta, se debe especificar un nombre, el id del elemento del DOM que será el contenedor donde se renderizará, y un objeto con valores para uno o más de los parámetros: Value, Subtitle, Description, Variation, Icon, Width, Animate. Asimismo, se pueden usar los métodos SetValue(), SetIcon(), etc. para fijar los valores.

CyanAir.CreateKpiCard("KPIVentasTrimestrales", "IdContenedor", {Value: 154, Width: "100%", Subtitle: "Ventas trimestrales", Description: "Total de ventas trimestre", Icon: "💰"});
KPIVentasTrimestrales.SetValue(254);
KPIVentasTrimestrales.SetVariation(55);

📈 Gráficos Ligeros (Native Charts)

Cyan Air incorpora varios tipos de gráficos ligeros para mostrar datos de forma visual sin penalizar el tiempo de carga de la aplicación. Estos gráficos son reactivos: se redibujan automáticamente si el contenedor cambia de tamaño.

SparkLine (Líneas de Tendencia)

Los SparkLine son gráficos minimalistas diseñados para mostrar la evolución de una métrica en espacios reducidos, como celdas de una tabla o dentro de una KpiCard.

CyanAir.CreateSparkline(
    "SparkVentas",
    "IdContenedor",
    {
        Data: [10, 15, 12, 18, 20, 17, 22, 30, 40, 50, 70],
        Width: 140,
        Height: 40,
        ShowArea: true
    }
);

📊 HistogramChart (Gráficos de Barras)

El HistogramChart es la herramienta ideal para comparar magnitudes entre diferentes categorías (por ejemplo, ventas por mes o usuarios por país). Acepta cuatro modos: absolute, percentage, stacked y stacked100, y hasta tres series de datos.

CyanAir.CreateHistogramChart("Histogram1", "IdContenedor",
    {
        Labels: ["Ene", "Feb", "Mar", "Abr", "May", "Jun"],
        Series: [
            { Name: "Ventas 2023", Data: [10, -50, 30, 25, 15, 35] },
            { Name: "Ventas 2024", Data: [15, -25, 35, 30, 20, 40] }
        ],
        Width: "100%",
        Height: "320px",
        ShowLegend: true,
        Mode: "stacked"
    }
);

8. Diagramación de Layouts

Para diagramar layouts, Cyan Air incluye varias clases de uso simple:

Todos los valores de estas clases pueden modificarse mediante SetStyle, como por ejemplo, el top de la clase .sticky para que se "pegue" a la altura que necesites, o cambiar el padding o el justify-content de la clase .row, etc.

🤝 Participación y Contribución

Este es un proyecto Open Source. Si deseas mejorar el motor de estilos, el sistema de mensajería o añadir nuevos componentes, tu Pull Request es bienvenido.

Cómo colaborar:

Fork: Crea una copia del repositorio en tu propia cuenta de GitHub.
Branch: Crea una rama descriptiva: git checkout -b feature/NuevaFuncionalidad
Code: Edita el archivo fuente en src/cyan-air.ts.
Push: Sube los cambios a tu copia (fork): git push origin feature/NuevaFuncionalidad
Pull Request (PR): Desde GitHub, envía una solicitud detallando tus cambios para que puedan ser integrados en la rama principal.

¡Muchísimas gracias por ayudar a mejorar Cyan Air!

📜 Licencia

Este proyecto está bajo la Licencia MIT.