# 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).
- **View Switcher (`<neural-view-switcher>`)**: Cápsula selectora de vistas jerárquicas/en cascada (estándar ERP).
- **Action Menu (`<neural-action-menu>`)**: Menú desplegable '•••' para más acciones secundarias.
- **Record Navigator (`<neural-record-navigator>`)**: Cápsula de paginación entre registros en vistas de detalle de entidad (Frappe ERP standard).

### 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)

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

```html
<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`.

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

```html
<!-- 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.