Orbiq Neural UI Kit

Una biblioteca de componentes de interfaz de usuario de alto rendimiento, diseñada específicamente para el ecosistema modular de Orbiq Neural y fuertemente inspirada en las estéticas limpias, minimalistas y altamente funcionales.

A partir de la versión 0.1.0, neural-ui-kit adopta la metodología de Diseño Atómico (Atomic Design). Este marco de trabajo nos permite pensar en la interfaz de usuario como un ecosistema de bloques de construcción escalables, facilitando la creación rápida de plataformas y catálogos de componentes modulares.

Filosofía de Diseño

• Estética limpia: Uso intensivo de espacios en blanco, bordes sutiles y sombras suaves (box-shadow) en lugar de contenedores delimitados por líneas duras.
• Micro-interacciones: Transiciones suaves en estados de hover, focus y active.
• Integración con Tailwind CSS: Totalmente configurable mediante variables y clases utilitarias de Tailwind v4.
• Iconografía: Uso estandarizado de iconos de lucide-icons.
• Diseño Atómico: Arquitectura predecible (Átomos -> Moléculas -> Organismos -> Plantillas -> Páginas).

Catálogo de Componentes (Arquitectura Atómica)

A continuación, se detalla la lista de componentes disponibles estructurados por su nivel atómico. Cada bloque está diseñado para integrarse perfectamente con el siguiente nivel de complejidad.

1. Átomos (Atoms)

Elementos de UI básicos e indivisibles. No dependen de otros componentes.

• Avatar (<neural-avatar>): Representación visual de usuarios (círculo o cuadrado).
• Badge (<neural-badge>): Pequeñas etiquetas de información de estado o categorización.
• Button (<neural-button>): Botón estándar con múltiples variantes, tamaños y estados.
• Checkbox (<neural-checkbox>): Selector booleano simple.
• Divider (<neural-divider>): Línea separadora estructural.
• Error Message (<neural-error-message>): Texto estandarizado para feedback de validación.
• FilterBuilder (<neural-filter-builder>): Organismo interactivo para construir filtros dinámicos y pasárselos a tablas o listas.
• Form Label (<neural-form-label>): Etiqueta tipográfica para campos de entrada.
• Icon (<neural-icon>): Componente envoltorio para renderizar vectores de Lucide.
• Loading Indicator & Text: Elementos visuales de carga y estados de espera.
• Progress (<neural-progress>): Barra de progreso simple.
• Radio (<neural-radio>): Botón de selección única.
• Skeleton (<neural-skeleton>): Bloques de carga (placeholders) para contenido asíncrono.
• Slider (<neural-slider>): Control de selección de rango numérico.
• Spinner (<neural-spinner>): Animación circular de carga.
• Switch (<neural-switch>): Interruptor booleano (toggle).
• Text Input & Textarea: Entradas de texto básicas.
• Tooltip (<neural-tooltip>): Información adicional contextual al pasar el ratón.
• Duration (<neural-duration>): Componente base para visualización de tiempo.

2. Moléculas (Molecules)

Grupos simples de átomos que funcionan juntos como una unidad funcional cohesiva.

• Accordion (<neural-accordion>): Paneles apilados expandibles.
• Alert (<neural-alert>): Cajas de advertencia e información estática estructurada.
• Breadcrumbs (<neural-breadcrumbs>): Rutas de navegación compuestas por enlaces e iconos.
• Combobox & Select: Selectores de listas desplegables.
• Dropdown (<neural-dropdown>): Selector flotante (popover) con soporte para sub-menús.
• Form Control (<neural-form-control>): Envoltorio estandarizado para inputs, uniendo label, input y error-message.
• Hover Card (<neural-hover-card>): Tarjeta flotante con información detallada activada por hover.
• Input Labeling: Sistema de etiquetado avanzado para inputs.
• Item List Row (<neural-item-list-row>): Fila estandarizada para listas de elementos.
• Keyboard Shortcut (<neural-keyboard-shortcut>): Renderizado visual de atajos de teclado.
• Popover (<neural-popover>): Tarjetas flotantes controladas por interacciones de usuario.
• Tabs (<neural-tabs>): Contenedor de pestañas de contenido intercambiables.
• Multi Select & Multi Email Input: Entradas de texto complejas con selección múltiple.
• Password Input (<neural-password>): Input de texto combinado con icono de revelar/ocultar.
• Time Picker (<neural-time-picker>): Selector de horas y minutos.
• Rating (<neural-rating>): Selector de calificación interactivo (ej. estrellas).

3. Organismos (Organisms)

Componentes relativamente complejos que forman secciones distintas y autónomas de una interfaz, compuestos por moléculas y átomos.

• Bottom Sheet (<neural-bottom-sheet>): Panel modal que emerge desde la parte inferior (ideal para móvil).
• Calendar & Date Picker: Selectores de fechas y visualización de calendarios completos.
• Charts (<neural-charts>): Contenedores para renderizado de gráficos complejos.
• Code Editor (<neural-code-editor>): Organismo completo de edición de código con sintaxis.
• Command Palette (<neural-command-palette>): Paleta de comandos (Spotlight) para navegación y acciones rápidas.
• Context Menu (<neural-context-menu>): Menú contextual activado por clic derecho.
• Dialog (<neural-dialog>): Ventanas modales emergentes completas con cabeceras y acciones.
• File Uploader (<neural-file-uploader>): Zona completa de arrastrar y soltar para carga de archivos.
• Floating Window (<neural-floating-window>): Ventanas flotantes arrastrables en el entorno de escritorio.
• List View (<neural-list-view>): Renderizado complejo de tablas y vistas de datos estructuradas.
• Menu (<neural-menu>): Organismo de menú estructurado.
• Mobile Nav (<neural-mobile-nav>): Barra de navegación adaptada a dispositivos móviles.
• Page Header (<neural-page-header>): Cabecera estándar de página con título, migas de pan y acciones.
• Rail (<neural-rail>): Barra lateral colapsada (rail) para navegación rápida.
• Scroll Area (<neural-scroll-area>): Contenedor especializado para manejo de desbordamiento de contenido.
• Sidebar (<neural-sidebar>): Contenedor estructural lateral completo para navegación principal.
• Settings Dialog (<neural-settings-dialog>): Modal de configuración preconstruido con navegación interna.
• Text Editor (<neural-text-editor>): Editor de texto enriquecido (Rich Text).
• Theme Switcher (<neural-theme-switcher>): Organismo para controlar los modos de diseño (claro/oscuro).
• Toast (<neural-toast>): Sistema de notificaciones efímeras (snacks).
• Tree (<neural-tree>): Representación de datos jerárquicos expansibles.

4. Plantillas (Templates)

Objetos a nivel de página que articulan la estructura subyacente ubicando organismos en el diseño.

• Desktop Shell (<neural-desktop-shell>): Estructura base para el entorno de trabajo de escritorio (sidebar + header + contenido).
• Mobile Shell (<neural-mobile-shell>): Estructura base para el entorno móvil (bottom nav + contenido).

Uso (Ejemplo Básico)

1. Elementos Sueltos (Átomos)

// Importa desde los bloques atómicos
import { NeuralButtonComponent, NeuralAvatarComponent } from 'orbiq-neural-ui-kit'; 

<neural-button variant="subtle" theme="blue" size="md">
  Guardar
</neural-button>

<neural-avatar label="John Doe" size="lg" shape="circle"></neural-avatar>

2. Ensamblando una Página (Plantilla Desktop)

El poder del Diseño Atómico brilla al usar las Plantillas y llenarlas de Organismos y Moléculas. Aquí tienes un ejemplo de cómo estructurar una página completa usando el Desktop Shell.

import { 
  NeuralDesktopShellComponent, 
  NeuralSidebarComponent, 
  NeuralPageHeaderComponent 
} from 'orbiq-neural-ui-kit';

<!-- La Plantilla principal que dicta el layout general -->
<neural-desktop-shell>
  
  <!-- Organismo: Barra lateral inyectada en el slot 'sidebar' -->
  <neural-sidebar sidebar>
    <!-- Contenido de navegación de tu aplicación -->
  </neural-sidebar>

  <!-- Organismo: Cabecera inyectada en el slot 'header' -->
  <neural-page-header header title="Dashboard Principal">
    <!-- Átomos/Moléculas: Acciones en la cabecera -->
    <neural-button variant="solid" theme="gray" actions>
      Nuevo Reporte
    </neural-button>
  </neural-page-header>

  <!-- Contenido Principal: Aquí se renderizarán las Páginas hijas -->
  <div class="p-6 h-full w-full bg-gray-50/50">
    <!-- El router-outlet cargará dinámicamente las páginas dentro del layout -->
    <router-outlet></router-outlet>
  </div>

  <!-- Organismo/Átomo: Footer opcional al final de la pantalla -->
  <footer footer class="border-t border-gray-200 p-4 text-center text-sm text-gray-500">
    © 2026 Orbiq Neural UI. Todos los derechos reservados.
  </footer>

</neural-desktop-shell>

Para documentación interactiva detallada de cada componente (Playground), por favor referirse a la ruta interna /system/components-playground dentro del ERP.