grmenu 0.1.6 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. checksums.yaml +4 -4
  2. data/GRmenu.rb +1834 -293
  3. data/README.md +430 -225
  4. data/data/help.txt +304 -0
  5. metadata +7 -3
data/README.md CHANGED
@@ -1,337 +1,542 @@
1
- <div align="center">
1
+ # GRmenu (Ruby) v3.0
2
2
 
3
- # GRmenu (Ruby)
3
+ **Suite TUI Profesional y Ligera para la Creacion de Interfaces de Linea de Comandos en Terminales TTY.**
4
4
 
5
- **Menús interactivos por teclado para terminal en modo TTY crudo, con soporte para Banners ASCII 3D, estilos y colores personalizados**
6
-
7
- Flechas arriba/abajo para moverte · `Enter` para elegir · `q` para salir
5
+ Menus interactivos por teclado, seleccion multiple con casillas de verificacion, controles deslizantes en tiempo real, renderizado de imagenes ANSI TrueColor de 24 bits, modo cromatico RGB animado a 30 FPS, modales nativos de confirmacion y texto, buscador instantaneo en vivo, cuadriculas bidimensionales, barras de progreso y banners 3D sin dependencias externas.
8
6
 
9
7
  [![Gem Version](https://badge.fury.io/rb/grmenu.svg)](https://badge.fury.io/rb/grmenu)
10
8
  [![License: MIT](https://img.shields.io/github/license/JoseEduardoGR/GRmenu)](LICENSE)
11
9
  [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/JoseEduardoGR/GRmenu)
10
+ [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.6-red.svg)](https://www.ruby-lang.org)
11
+
12
+ ---
12
13
 
13
- </div>
14
+ ## Tabla de Contenidos
15
+
16
+ 1. [Por que elegir GRmenu?](#-por-que-elegir-grmenu)
17
+ 2. [Instalacion y Requisitos](#-instalacion-y-requisitos)
18
+ 3. [Inicio Rapido en 10 Segundos](#-inicio-rapido-en-10-segundos)
19
+ 4. [Guia de Componentes y Caracteristicas](#-guia-de-componentes-y-caracteristicas)
20
+ - [1. Menu Interactivo Principal (Buscador, Grid 2D y Paginacion)](#1-menu-interactivo-principal)
21
+ - [2. Seleccion Multiple con Checkboxes (GRmenu.checkbox)](#2-seleccion-multiple-con-checkboxes)
22
+ - [3. Control Deslizante Interactivo (GRmenu.slider)](#3-control-deslizante-interactivo)
23
+ - [4. Renderizado Universal de Imagenes (GRmenu.image)](#4-renderizado-universal-de-imagenes)
24
+ - [5. Modales Nativos de Confirmacion y Entrada (confirm e input)](#5-modales-nativos-de-confirmacion-y-entrada)
25
+ - [6. Modo RGB Chroma Wave Animado a 30 FPS](#6-modo-rgb-chroma-wave-animado)
26
+ - [7. Barra de Progreso y Spinner de Carga](#7-barra-de-progreso-y-spinner-de-carga)
27
+ - [8. Banners 3D y Lineas Divisorias](#8-banners-3d-y-lineas-divisorias)
28
+ - [9. Modulo Independiente de Color (Color / C)](#9-modulo-independiente-de-color)
29
+ 5. [Catalogo Visual de Fuentes 3D (1 al 10)](#-catalogo-visual-de-fuentes-3d)
30
+ 6. [Catalogo Visual de Marcos y Bordes (1 al 20)](#-catalogo-visual-de-marcos-y-bordes)
31
+ 7. [Referencia Exhaustiva de la API](#-referencia-exhaustiva-de-la-api)
32
+ 8. [Mapa de Controles y Teclado](#-mapa-de-controles-y-teclado)
33
+ 9. [Recetas y Casos de Uso del Mundo Real](#-recetas-y-casos-de-uso-del-mundo-real)
34
+ 10. [Licencia](#-licencia)
14
35
 
15
36
  ---
16
37
 
17
- ## ✨ Características
38
+ ## Por que elegir GRmenu?
18
39
 
19
- - 🎮 **Navegación con flechas** — arriba/abajo para moverte, `Enter` para ejecutar, `q` para salir.
20
- - 🔤 **10 Fuentes ASCII 3D para Banners** — fuentes tridimensionales (ANSI Shadow, Slant, Doom, Graffiti, Modular, Wire, Block, Stars, etc.).
21
- - 🎨 **20 estilos de borde** — desde ASCII clásico hasta caracteres Unicode dobles, curvas redondeadas y bloques.
22
- - 🌈 **Paleta de colores completa** — personalización individual de marco, título, banner, subtítulo, divisores, opciones y foco activo con 2 niveles de brillo.
23
- - 📐 **Centrado simétrico automático** — alinea y centra automáticamente subtítulos y menús de opciones respecto al ancho de banners grandes.
24
- - 🛠️ **Helpers nativos en modo crudo** — `clear_screen`, `continue`, `banner`, `div` y `help` sin subprocesos lentos del sistema.
25
- - 💻 **100% Multiplataforma** — compatible con Linux, macOS y Windows (PowerShell, CMD, Windows Terminal, VS Code).
26
- - 📦 **Cero dependencias externas** — utiliza únicamente la librería estándar `io/console`.
40
+ - **Cero Dependencias Externas:** Funciona exclusivamente con la libreria estandar de Ruby (`io/console`, `json`, `zlib`), sin gemas pesadas ni binarios nativos requeridos.
41
+ - **Modo TTY Crudo Instantaneo:** Control milimetrico de la consola sin parpadeo de pantalla y con captura instantanea de eventos de teclado (0 ms de latencia).
42
+ - **Animaciones Sin Lag a 30 FPS:** Motor de renderizado reactivo no bloqueante basado en `IO.select` que permite efectos visuales dinamicos continuos sin saturar la CPU ni bloquear la entrada del usuario.
43
+ - **Multiplataforma Real:** Totalmente compatible con Linux, macOS y Windows (Windows Terminal, PowerShell, CMD y VS Code Terminal).
44
+ - **Diseno Modular y Expresivo:** Desde un simple menu de 3 lineas hasta complejas suites de instalacion, paneles DevOps o herramientas de configuracion.
27
45
 
28
46
  ---
29
47
 
30
- ## 📦 Instalación
48
+ ## Instalacion y Requisitos
49
+
50
+ Requiere **Ruby >= 2.6.0**.
51
+
52
+ ### Via RubyGems
31
53
 
32
54
  ```bash
33
55
  gem install grmenu
34
56
  ```
35
57
 
36
- O si trabajás con el archivo directamente en tu proyecto:
58
+ ### Via Gemfile
37
59
 
38
60
  ```ruby
39
- require_relative "GRmenu"
61
+ gem 'grmenu', '~> 3.0'
40
62
  ```
41
63
 
42
- <sub>Requiere Ruby ≥ 2.6.</sub>
43
-
44
- ---
45
-
46
- ## 💡 Cómo se pasan las opciones y todos los parámetros
47
-
48
- `GRmenu` permite pasar métodos directos, símbolos, arreglos con nombres personalizados, bloques lambda/procs y helpers. Además, acepta todos los parámetros de configuración visual en la instanciación:
64
+ ### Requerimiento directo en scripts
49
65
 
50
66
  ```ruby
51
- menu = GRmenu.new(
52
- [
53
- method(:iniciar_servidor), # 1. Method (auto-capitaliza: "Iniciar Servidor")
54
- :crear_respaldo, # 2. Symbol (auto-capitaliza: "Crear Respaldo")
55
- ["Métricas del Sistema", method(:ver_metricas)], # 3. Array ["Nombre Personalizado", acción]
56
- ["Ejecutar Lambda", -> { puts Color.pink("Lambda!"); GRmenu.continue }], # 4. Lambda/Proc
57
- ["Probar Banner Helper", method(:prueba_banner_rapido)], # 5. Helper GRmenu.banner
58
- ["Ver Ayuda y Referencia", method(:ver_ayuda_completa)], # 6. Helper GRmenu.help
59
- method(:salir) # 7. Salir
60
- ],
61
- banner: "DEV OPS", # Texto gigante en arte ASCII 3D
62
- title: "Panel de Control", # Título en el marco de opciones
63
- subtitle: "Consola de Administración\nUsa las flechas y Enter", # Subtítulo (soporta saltos de línea \n)
64
- font: 1, # Fuente del banner (1 al 10, por defecto 1: ANSI Shadow 3D)
65
- style: 7, # Estilo de marco de opciones (1 al 20, ej: 7=redondeado, 3=doble)
66
- banner_style: 3, # Estilo de marco del banner (1 al 20, ej: 3=doble línea)
67
- divider: true, # Líneas divisorias a la par del banner (true, false o número)
68
- center: true # Centrado automático del menú y subtítulo respecto al banner
69
- )
67
+ require 'GRmenu'
70
68
  ```
71
69
 
72
70
  ---
73
71
 
74
- ## 🌟 Ejemplo Completo de Uso (`e.rb`)
72
+ ## Inicio Rapido en 10 Segundos
75
73
 
76
- A continuación se muestra el archivo de ejemplo completo [`e.rb`](e.rb) con acciones, helpers, configuración de estilos, fuentes y colores:
74
+ Crea un archivo llamado `app.rb` y ejecuta `ruby app.rb`:
77
75
 
78
76
  ```ruby
79
- # frozen_string_literal: true
80
-
81
- require_relative "GRmenu"
77
+ require 'GRmenu'
82
78
 
83
- # 1. Definición de acciones/métodos
84
- def iniciar_servidor
79
+ def iniciar_servicio
85
80
  GRmenu.clear_screen
86
- puts Color.bright_green("-> Servidor iniciado correctamente en el puerto 3000.")
81
+ puts Color.bright_green("-> Servicio iniciado exitosamente en http://localhost:3000")
87
82
  GRmenu.continue
88
83
  end
89
84
 
90
- def crear_respaldo
85
+ def ver_estado
91
86
  GRmenu.clear_screen
92
- puts Color.bright_cyan("-> Creando respaldo de la base de datos...")
87
+ puts Color.bright_cyan("-> Estado: Servidor Operativo | Memoria: 45 MB | Conexiones: 12")
93
88
  GRmenu.continue
94
89
  end
95
90
 
96
- def ver_metricas
97
- GRmenu.clear_screen
98
- puts Color.bright_magenta("-> CPU: 12% | RAM: 4.2 GB | Estado: Operativo")
99
- GRmenu.continue
100
- end
91
+ menu = GRmenu.new(
92
+ [
93
+ ["Iniciar Servicio", method(:iniciar_servicio), "Lanza el worker en segundo plano"],
94
+ ["Ver Estado", method(:ver_estado), "Muestra metricas de memoria y conexion"],
95
+ ["Salir", -> { exit(0) }, "Finaliza la ejecucion"]
96
+ ],
97
+ title: "Panel de Control",
98
+ banner: "MI APP",
99
+ style: 3
100
+ )
101
101
 
102
- def prueba_banner_rapido
103
- GRmenu.clear_screen
104
- # Helper para mostrar un banner estático o animado en cualquier momento
105
- GRmenu.banner("OK", 0, color: "green", level: 2, style: 3, font: 1)
106
- GRmenu.div(40, "green", 1, "═")
107
- puts Color.green(" Prueba completada con éxito.")
108
- GRmenu.div(40, "green", 1, "═")
109
- GRmenu.continue
110
- end
102
+ menu.draw
103
+ ```
111
104
 
112
- def ver_ayuda_completa
113
- GRmenu.clear_screen
114
- # Helper interactivo que imprime toda la guía y referencia de GRmenu
115
- GRmenu.help
116
- GRmenu.continue
117
- end
105
+ ---
118
106
 
119
- def salir
120
- GRmenu.clear_screen
121
- puts Color.bright_yellow("¡Sesión finalizada con éxito!")
122
- exit(0)
123
- end
107
+ ## Guia de Componentes y Caracteristicas
108
+
109
+ ### 1. Menu Interactivo Principal
110
+
111
+ El constructor `GRmenu.new` proporciona una experiencia interactiva completa con navegacion continua, paginacion automatica, buscador en vivo y organizacion en cuadricula 2D.
112
+
113
+ ```text
114
+ ╔═══════════════════════════════════════════╗
115
+ ║ Panel de Control ║
116
+ ║═══════════════════════════════════════════║
117
+ ║ Buscar: serv█ ║
118
+ ║═══════════════════════════════════════════║
119
+ ║ > [X] Servidor Web Nginx ║
120
+ ║ [ ] Servidor Base de Datos Postgres ║
121
+ ║───────────────────────────────────────────║
122
+ ║ * Proxy inverso HTTP de alto rendimiento ║
123
+ ╚═══════════════════════════════════════════╝
124
+ ```
125
+
126
+ #### Formatos de Opciones Aceptados
124
127
 
125
- # 2. Instanciación del menú con TODOS los parámetros disponibles
128
+ Puedes combinar cualquiera de los siguientes formatos en el array de opciones:
129
+
130
+ ```ruby
126
131
  menu = GRmenu.new(
127
132
  [
128
- method(:iniciar_servidor), # 1. Method (auto-capitaliza: "Iniciar Servidor")
129
- :crear_respaldo, # 2. Symbol (auto-capitaliza: "Crear Respaldo")
130
- ["Métricas del Sistema", method(:ver_metricas)], # 3. Array ["Nombre Personalizado", acción]
131
- ["Ejecutar Lambda", -> { puts Color.pink("Lambda!"); GRmenu.continue }], # 4. Lambda/Proc
132
- ["Probar Banner Helper", method(:prueba_banner_rapido)], # 5. Helper GRmenu.banner
133
- ["Ver Ayuda y Referencia", method(:ver_ayuda_completa)], # 6. Helper GRmenu.help
134
- method(:salir) # 7. Salir
133
+ # 1. Method directo (auto-formatea y capitaliza el nombre)
134
+ method(:iniciar_servidor),
135
+
136
+ # 2. Symbol (invoca el metodo global o del contexto)
137
+ :crear_respaldo,
138
+
139
+ # 3. Arreglo [Etiqueta, Accion]
140
+ ["Lanzar Proceso", method(:lanzar)],
141
+
142
+ # 4. Arreglo con Tooltip [Etiqueta, Accion, Descripcion]
143
+ ["Limpieza de Cache", method(:limpiar), "Vacia los temporales en disco"],
144
+
145
+ # 5. Bloque anonimo Proc o Lambda
146
+ ["Accion Rapida", -> { puts "Ejecutado!"; GRmenu.continue }, "Ejecuta bloque inline"],
147
+
148
+ # 6. Hash explicito
149
+ { name: "Configuracion", action: method(:config), desc: "Ajustes del sistema" }
135
150
  ],
136
- banner: "DEV OPS", # Texto gigante en arte ASCII 3D
137
- title: "Panel de Control", # Título en el marco de opciones
138
- subtitle: "Consola de Administración\nUsa las flechas y Enter", # Subtítulo (soporta saltos de línea \n)
139
- font: 1, # Fuente del banner (1 al 10, por defecto 1: ANSI Shadow 3D)
140
- style: 7, # Estilo de marco de opciones (1 al 20, ej: 7=redondeado, 3=doble)
141
- banner_style: 3, # Estilo de marco del banner (1 al 20, ej: 3=doble línea)
142
- divider: true, # Líneas divisorias a la par del banner (true, false o número)
143
- center: true # Centrado automático del menú y subtítulo respecto al banner
151
+ title: "Consola de Administracion",
152
+ banner: "SISTEMA",
153
+ search: true, # Activa buscador interactivo en vivo
154
+ columns: 2, # Cuadricula de 2 columnas con flechas izquierda/derecha
155
+ page_size: 6, # Paginacion con auto-scroll
156
+ style: 3
144
157
  )
145
158
 
146
- # 3. Configuración completa de colores y estilos (set_style / style_config)
147
- # Colores disponibles: "black", "gray", "red", "green", "yellow", "blue",
148
- # "magenta", "purple", "pink", "cyan", "aqua", "orange", "white"
149
- # Niveles de brillo: 1 = normal, 2 = brillante
150
-
151
- menu.set_style.font(1) # 1 = ANSI Shadow 3D, 2 = Slant 3D, 3 = Doom, etc.
152
- menu.set_style.banner("cyan", 2) # Color del banner ASCII
153
- menu.set_style.title("yellow", 2) # Color del título del recuadro
154
- menu.set_style.subtitle("white", 1)# Color del subtítulo/descripción
155
- menu.set_style.divider("blue", 1) # Color de las líneas divisorias
156
- menu.set_style.border("yellow", 1) # Color del borde del marco de opciones
157
- menu.set_style.options("white", 1) # Color de opciones no seleccionadas
158
- menu.set_style.focus("green", 2) # Color y brillo de la opción resaltada
159
-
160
- # 4. Dibujar y lanzar el menú interactivo
161
- # size_max / min_width define el ancho mínimo sugerido para el marco de opciones
162
- menu.draw(size_max: 38)
159
+ menu.draw(size_max: 44)
163
160
  ```
164
161
 
165
162
  ---
166
163
 
167
- ## 📖 Guía y Referencia Rápida en Consola (`GRmenu.help`)
164
+ ### 2. Seleccion Multiple con Checkboxes
168
165
 
169
- Para consultar en cualquier momento la lista de helpers, colores, fuentes, marcos y sintaxis directamente desde la terminal, podés ejecutar:
166
+ Permite al usuario seleccionar multiples elementos simultaneamente mediante casillas de verificacion interactivas `[X]` / `[ ]`.
170
167
 
171
- ```ruby
172
- GRmenu.help
168
+ ```text
169
+ ╔══════════════════ Instalador de Paquetes ══════════════════╗
170
+ ║ [X] Servidor Nginx Web ║
171
+ ║ [X] Base de Datos PostgreSQL 16 ║
172
+ ║ [ ] Almacen de Cache Redis 7.2 ║
173
+ ║ [X] Monitor Prometheus ║
174
+ ║────────────────────────────────────────────────────────────║
175
+ ║ Espacio: Marcar | a: Todos | n: Ninguno | Enter: Confirmar ║
176
+ ╚════════════════════════════════════════════════════════════╝
173
177
  ```
174
178
 
175
- O desde una instancia:
179
+ #### Codigo de Ejemplo:
176
180
 
177
181
  ```ruby
178
- menu.help
182
+ paquetes = [
183
+ ["Servidor Nginx Web", true, "Proxy inverso de alta velocidad"],
184
+ ["Base de Datos PostgreSQL 16", true, "Motor de datos principal"],
185
+ ["Almacen de Cache Redis 7.2", false, "Cache en memoria RAM"],
186
+ ["Monitor Prometheus", true, "Metricas y alertas"]
187
+ ]
188
+
189
+ seleccionados = GRmenu.checkbox(
190
+ paquetes,
191
+ title: "Instalador de Paquetes",
192
+ color: "rgb",
193
+ style: 3
194
+ )
195
+
196
+ puts "Elementos seleccionados: #{seleccionados.length}"
197
+ seleccionados.each do |elem|
198
+ nombre = elem.is_a?(Array) ? elem[0] : elem
199
+ puts " - [X] #{nombre}"
200
+ end
179
201
  ```
180
202
 
181
- Salida limpia y estructurada en consola:
203
+ **Teclas de Control en Checkbox:**
204
+ - `Espacio`: Alterna entre marcado `[X]` y desmarcado `[ ]`.
205
+ - `a` / `A`: Marca todos los elementos (*Select All*).
206
+ - `n` / `N`: Desmarca todos los elementos (*Deselect All*).
207
+ - `i` / `I`: Invierte la seleccion actual.
208
+ - `Enter`: Confirma y devuelve el arreglo de elementos seleccionados.
209
+ - `q` / `Esc`: Cancela y devuelve un arreglo vacio `[]`.
210
+
211
+ ---
212
+
213
+ ### 3. Control Deslizante Interactivo
214
+
215
+ Permite seleccionar numericamente un valor o porcentaje dentro de un rango mediante una barra horizontal en tiempo real.
182
216
 
183
217
  ```text
184
- ╔══════════════════════════════════════════════════════════════╗
185
- ║ GRmenu - Guia y Referencia Rapida ║
186
- ║ Navegacion interactiva en terminal TTY ║
187
- ╚══════════════════════════════════════════════════════════════╝
188
-
189
- [1] HELPERS NATIVOS EN MODO CRUDO
190
- ────────────────────────────────────────────────────────────────
191
- GRmenu.clear_screen (o GRmenu.clr)
192
- * Limpia la terminal al instante con secuencias ANSI.
193
- GRmenu.continue(mensaje)
194
- * Pausa interactiva: espera una sola tecla en modo TTY crudo.
195
- GRmenu.banner(texto, delay, color:, level:, style:, font:)
196
- * Renderiza banner ASCII 3D con marco y animacion opcional.
197
- GRmenu.div(longitud, color, level, char)
198
- * Dibuja linea divisoria horizontal adaptable a la consola.
199
- GRmenu.help
200
- * Imprime esta guia visual interactiva en consola.
218
+ ╔══════════════ Asignar Memoria RAM ══════════════╗
219
+ ║ [████████████████████░░░░░░░░░░] 16 GB ║
220
+ ║ ║
221
+ ║ ← / → Ajustar paso | ↑ / ↓ Salto x5 | Enter OK ║
222
+ ╚═════════════════════════════════════════════════╝
223
+ ```
224
+
225
+ #### Codigo de Ejemplo:
226
+
227
+ ```ruby
228
+ ram = GRmenu.slider(
229
+ "Asignar Memoria RAM",
230
+ min: 1,
231
+ max: 64,
232
+ step: 1,
233
+ default: 16,
234
+ unit: "GB",
235
+ color: "rgb",
236
+ style: 3
237
+ )
238
+
239
+ puts "Memoria configurada: #{ram} GB"
201
240
  ```
202
241
 
242
+ **Teclas de Control en Slider:**
243
+ - `←` / `→` o `h` / `l`: Ajusta el valor paso a paso (`step`).
244
+ - `↑` / `↓` o `k` / `j`: Salto rapido de 5 pasos.
245
+ - `Enter`: Guarda y retorna el numero exacto (`Integer` o `Float`).
246
+ - `q` / `Esc`: Cancela y retorna el valor por defecto.
247
+
203
248
  ---
204
249
 
205
- ## 🕹️ Controles
250
+ ### 4. Renderizado Universal de Imagenes
251
+
252
+ Decodifica y renderiza cualquier formato de imagen (PNG, JPEG, JPG, WEBP, GIF, BMP) con micro-pixeles ANSI TrueColor de 24 bits y escalado proporcional exacto.
253
+
254
+ #### Renderizado Directo en Consola:
255
+
256
+ ```ruby
257
+ # Renderiza una imagen centrada dentro de un marco estilizado
258
+ GRmenu.image("fondo.jpg", width: 60, color: "rgb", style: 3)
259
+ ```
260
+
261
+ #### Como Cabecera Superior en un Menu:
206
262
 
207
- | Tecla | Acción |
208
- |-------------|---------------------------|
209
- | `↑` | Mover selección arriba |
210
- | `↓` | Mover selección abajo |
211
- | `Enter` | Ejecutar opción seleccionada |
212
- | `q` | Salir del menú |
263
+ ```ruby
264
+ menu = GRmenu.new(
265
+ [
266
+ ["Escanear Red", method(:escanear)],
267
+ ["Ver Reporte", method(:reporte)],
268
+ ["Salir", -> { exit(0) }]
269
+ ],
270
+ image: "logo.png",
271
+ image_width: 44,
272
+ title: "Security Toolset",
273
+ style: 3
274
+ )
275
+
276
+ menu.draw
277
+ ```
213
278
 
214
279
  ---
215
280
 
216
- ## 🔤 Fuentes ASCII 3D para Banners (`font: 1` al `10`)
217
-
218
- | ID | Estilo | Muestra (`RUBY`) |
219
- |:--:|--------------------------|------------------|
220
- | **`1`** | **ANSI Shadow 3D (Default)** | `██████╗ ██╗ ██╗ ██████╗ ██╗ ██╗` |
221
- | **`2`** | **Slant 3D (FIGlet)** | ` ____ __ __ ____ __ __` |
222
- | **`3`** | **Doom / Standard 3D** | ` ____ _ _ ____ __ __` |
223
- | **`4`** | **Graffiti Shadow 3D** | ` ,---. ,--. ,--. ,---. ,--. ,--.` |
224
- | **`5`** | **Small Slant / Mini 3D**| ` ___ _ _ ___ _ _` |
225
- | **`6`** | **Modular Pipe 3D** | ` _____ _____ _____ _____` |
226
- | **`7`** | **Bubble / Round Gothic**| ` ____ _ _ ____ _ _` |
227
- | **`8`** | **Double-Line Wire 3D** | ` ╔═════╗ ║ ║ ╔════╗ ║ ║` |
228
- | **`9`** | **Solid Fat 3D Block** | ` ██████▄ ██ ██ ██████▄ ██ ██` |
229
- | **`10`**| **Arcade Stars Matrix** | ` ★★★★ ★ ★ ★★★★ ★ ★` |
281
+ ### 5. Modales Nativos de Confirmacion y Entrada
282
+
283
+ Cuadros de dialogo emergentes bloqueantes que capturan respuestas del usuario de forma directa y visual.
284
+
285
+ #### Modal de Confirmacion (`GRmenu.confirm`):
286
+
287
+ ```ruby
288
+ # Dialogo interactivo Si / No con seleccion por flechas y teclado
289
+ if GRmenu.confirm("Deseas aplicar los cambios en produccion?", default: true, color: "rgb", style: 3)
290
+ puts Color.bright_green("-> Cambios aplicados con exito.")
291
+ else
292
+ puts Color.bright_red("-> Operacion cancelada.")
293
+ end
294
+ ```
295
+
296
+ #### Cuadro de Entrada de Texto (`GRmenu.input`):
297
+
298
+ ```ruby
299
+ # Entrada interactiva con cursor en vivo
300
+ nombre = GRmenu.input("Ingresa tu nombre de usuario:", default: "admin", color: "rgb", style: 3)
301
+
302
+ # Modo password para claves secretas (oculta caracteres con asteriscos)
303
+ token = GRmenu.input("Ingresa tu API Token:", password: true, color: "magenta", style: 7)
304
+ ```
230
305
 
231
306
  ---
232
307
 
233
- ## 🖼️ Estilos de Marco (`style` / `banner_style: 1` al `20`)
234
-
235
- | `style` | Vista previa | `style` | Vista previa |
236
- |:---:|:---|:---:|:---|
237
- | 1 | `#===#` | 11 | `░░░░░` |
238
- | 2 | `┌───┐` *(Línea simple)* | 12 | `█████` |
239
- | 3 | `╔═══╗` *(Doble línea - Default banner)* | 13 | `*****` |
240
- | 4 | `┏━━━┓` *(Línea gruesa)* | 14 | `+++++` |
241
- | 5 | `╒═══╕` | 15 | `=====` |
242
- | 6 | `╓───╖` | 16 | `~~~~~` |
243
- | 7 | `╭───╮` *(Curvas redondeadas)* | 17 | `-----` |
244
- | 8 | `▛▀▀▀▜` *(Bloques outline)* | 18 | `◆◆◆◆◆` |
245
- | 9 | `▓▓▓▓▓` | 19 | `●○○○●` *(Círculos - Default opciones)* |
246
- | 10 | `▒▒▒▒▒` | 20 | `★☆☆☆★` *(Estrellas)* |
308
+ ### 6. Modo RGB Chroma Wave Animado
309
+
310
+ Puedes activar el modo de color animado pasando `"rgb"`, `"rainbow"` o `"chroma"` a cualquier componente visual. El motor genera una onda sinusoidal horizontal que fluye suavemente a 30 FPS en segundo plano sin producir retraso en el teclado.
311
+
312
+ ```ruby
313
+ menu = GRmenu.new(opciones, banner: "CHROMA", title: "RGB Wave Panel")
314
+
315
+ menu.set_style.banner("rgb") # Letras 3D en degradado continuo
316
+ menu.set_style.title("rgb") # Titulo de cabecera en RGB
317
+ menu.set_style.border("rgb") # Marco exterior multicolor
318
+ menu.set_style.divider("rgb") # Lineas divisorias animadas
319
+ menu.set_style.focus("rgb") # Cursor enfocado pulsando en RGB
320
+ menu.set_style.options("rgb") # Texto de opciones en tono suave
321
+
322
+ menu.draw
323
+ ```
247
324
 
248
325
  ---
249
326
 
250
- ## 🎨 Paleta de Colores y Módulo `Color`
327
+ ### 7. Barra de Progreso y Spinner de Carga
328
+
329
+ #### Barra de Progreso (`GRmenu.progress`):
251
330
 
252
331
  ```ruby
253
- puts Color.green("Texto en verde")
254
- puts Color.bright_cyan("Cian brillante")
255
- puts Color.yellow("Texto en amarillo")
256
- puts Color.bright_magenta("Magenta brillante")
257
- puts Color.purple("Texto en morado")
258
- puts Color.orange("Texto en naranja")
259
- puts Color.pink("Texto en rosa")
260
- puts Color.gray("Texto en gris")
332
+ GRmenu.progress(100, title: "Descargando Actualizacion", color: "rgb", style: 3) do |bar|
333
+ 10.times do |i|
334
+ sleep 0.1
335
+ bar.advance(10, status: "Procesando bloque #{i + 1} de 10...")
336
+ end
337
+ end
261
338
  ```
262
339
 
263
- Colores soportados: `black`, `gray`, `red`, `green`, `yellow`, `blue`, `magenta`, `purple`, `pink`, `cyan`, `aqua`, `orange`, `white`.
340
+ #### Spinner Animado (`GRmenu.spinner`):
341
+
342
+ ```ruby
343
+ resultado = GRmenu.spinner("Conectando con el cluster remoto...", color: "rgb") do
344
+ # Simula tarea pesada
345
+ sleep 1.5
346
+ "Conexion Establecida"
347
+ end
348
+
349
+ puts Color.bright_green("-> #{resultado}")
350
+ ```
264
351
 
265
352
  ---
266
353
 
267
- ## 🛠️ Helpers Nativos en Modo Crudo
354
+ ### 8. Banners 3D y Lineas Divisorias
268
355
 
269
356
  ```ruby
270
- # 1. Limpia la pantalla al instante con secuencias ANSI
271
- GRmenu.clear_screen # o GRmenu.clr
357
+ # Imprime un banner en arte ASCII 3D con retardo opcional de animacion
358
+ GRmenu.banner("ADMIN", 0, color: "rgb", style: 3, font: 1)
272
359
 
273
- # 2. Imprime un banner o logo gigante responsivo
274
- GRmenu.banner("SECURE", 0, color: "magenta", style: 3, font: 1)
360
+ # Imprime una linea divisoria horizontal con ajuste automatico al ancho de terminal
361
+ GRmenu.div(60, "rgb", 1, "═")
362
+ ```
363
+
364
+ ---
275
365
 
276
- # 3. Línea divisoria horizontal adaptable
277
- GRmenu.div(60, "blue")
366
+ ### 9. Modulo Independiente de Color
278
367
 
279
- # 4. Pausa de consola que espera una sola tecla en modo TTY crudo
280
- GRmenu.continue("Presiona cualquier tecla para continuar...")
368
+ El modulo `Color` (o su alias `C`) permite pintar cadenas de texto directamente con secuencias ANSI y TrueColor:
281
369
 
282
- # 5. Guía interactiva en consola
283
- GRmenu.help
370
+ ```ruby
371
+ # Modo Arcoiris RGB Dinamico
372
+ puts Color.rgb("Texto degradado en onda horizontal multicolor")
373
+
374
+ # Metodos directos por color (Nivel 1 Normal / Nivel 2 Brillante)
375
+ puts Color.bright_green("Verde brillante")
376
+ puts Color.bright_cyan("Cian brillante")
377
+ puts Color.bright_magenta("Magenta brillante")
378
+ puts Color.bright_yellow("Amarillo brillante")
379
+ puts Color.bright_red("Rojo brillante")
380
+ puts Color.orange("Naranja")
381
+ puts Color.purple("Morado")
382
+ puts Color.pink("Rosa")
383
+ puts Color.gray("Gris")
384
+ puts Color.white("Blanco")
385
+
386
+ # Atajos ultra-cortos de 1 o 2 letras
387
+ puts Color.g("Verde")
388
+ puts Color.cy("Cian")
389
+ puts Color.r("Rojo")
390
+ puts Color.y("Amarillo")
391
+ puts Color.w("Blanco")
392
+ puts Color.gr("Gris")
284
393
  ```
285
394
 
286
395
  ---
287
396
 
288
- ## 📖 Referencia de la API
397
+ ## Catalogo Visual de Fuentes 3D
289
398
 
290
- ### `GRmenu.new(functions, ...)`
399
+ Configura la tipografia mediante el parametro `font: 1..10`:
291
400
 
292
- | Parámetro | Tipo | Descripción |
293
- |------------------|------------|-------------|
294
- | `functions` | `Array` | Opciones a mostrar (`Method`, `Symbol`, `Array ["Nombre", acción]`, `Proc`/`lambda`). |
295
- | `banner:` | `String` | Texto gigante a renderizar en arte ASCII 3D arriba del menú. |
296
- | `title:` | `String` | Título en la cabecera del marco de opciones. |
297
- | `subtitle:` | `String` | Subtítulo o descripción (soporta múltiples líneas con `\n`). |
298
- | `font:` | `Integer` | Fuente ASCII 3D del banner (1 al 10, default 1). |
299
- | `style:` | `Integer` | Estilo de marco para las opciones (1 al 20, default 19). |
300
- | `banner_style:` | `Integer` | Estilo de marco para el banner (1 al 20, default 3). |
301
- | `divider:` | `Boolean` | Dibuja líneas divisorias a la par del ancho del banner. |
302
- | `center:` | `Boolean` | Centra simétricamente el subtítulo y menú de opciones (default `true`). |
401
+ | ID | Nombre de Fuente | Muestra Visual |
402
+ |:--:|:-----------------|:---------------|
403
+ | `1` | **ANSI Shadow 3D** *(Default)* | `██████╗ ██╗ ██╗` |
404
+ | `2` | **Slant 3D** | ` ____ __ __` |
405
+ | `3` | **Doom / Standard 3D** | ` ____ _ _` |
406
+ | `4` | **Graffiti Shadow 3D** | ` ,---. ,--. ,--.` |
407
+ | `5` | **Small Slant / Mini 3D** | ` ___ _ _` |
408
+ | `6` | **Modular Pipe 3D** | ` _____ _____` |
409
+ | `7` | **Bubble / Round Gothic** | ` ____ _ _` |
410
+ | `8` | **Double-Line Wire 3D** | ` ╔═════╗ ║ ║` |
411
+ | `9` | **Solid Fat 3D Block** | ` ██████▄ ██ ██` |
412
+ | `10`| **Arcade Stars Matrix** | ` ★★★★ ★ ★` |
303
413
 
304
- ### `menu.set_style`
414
+ ---
305
415
 
306
- | Método | Descripción |
307
- |-------------------------------------|-------------------------------------------|
308
- | `set_style.font(id)` | Cambia el tipo de fuente ASCII 3D (1..10). |
309
- | `set_style.banner(color, level=2)` | Color y brillo del banner ASCII 3D. |
310
- | `set_style.title(color, level=2)` | Color y brillo del título del marco. |
311
- | `set_style.subtitle(color, level=1)`| Color y brillo del subtítulo. |
312
- | `set_style.divider(color, level=1)` | Color y brillo de las líneas divisorias. |
313
- | `set_style.border(color, level=1)` | Color y brillo del marco de opciones. |
314
- | `set_style.options(color, level=1)` | Color y brillo de opciones no activas. |
315
- | `set_style.focus(color, level=2)` | Color y brillo de la opción resaltada. |
416
+ ## Catalogo Visual de Marcos y Bordes
316
417
 
317
- ### `menu.draw(size_max: 20)`
418
+ Configura el diseno del marco mediante el parametro `style: 1..20`:
318
419
 
319
- Inicia el menú interactivo con navegación por teclado y bloquea el hilo hasta que el usuario elige una opción (`Enter`) o sale (`q`).
420
+ | ID | Muestra | ID | Muestra | ID | Muestra | ID | Muestra |
421
+ |:--:|:--------|:--:|:--------|:--:|:--------|:--:|:--------|
422
+ | `1` | `#####` (Hash) | `6` | `╓───╖` (Mixto) | `11`| `░░░░░` (Sombra suave) | `16`| `~~~~~` (Ondas) |
423
+ | `2` | `┌───┐` (Simple) | `7` | `╭───╮` (Curvas) | `12`| `█████` (Bloque) | `17`| `-----` (Guion) |
424
+ | `3` | `╔═══╗` (Doble) | `8` | `▛▀▀▀▜` (Outline) | `13`| `*****` (Asterisco) | `18`| `◆◆◆◆◆` (Rombos) |
425
+ | `4` | `┏━━━┓` (Gruesa) | `9` | `▓▓▓▓▓` (Sombra oscura) | `14`| `+++++` (Cruces) | `19`| `●○○○●` (Circulos) |
426
+ | `5` | `╒═══╕` (Mixto) | `10`| `▒▒▒▒▒` (Sombra media) | `15`| `=====` (Doble simple) | `20`| `★☆☆☆★` (Estrellas) |
320
427
 
321
428
  ---
322
429
 
323
- ## 🤝 Contribuir
430
+ ## Referencia Exhaustiva de la API
431
+
432
+ ### Constructor `GRmenu.new(functions, **opciones)`
433
+
434
+ | Parametro | Tipo | Valor por Defecto | Descripcion |
435
+ |:----------|:-----|:------------------|:------------|
436
+ | `functions` | `Array` | *Obligatorio* | Lista de metodos, simbolos, arrays `[nombre, accion, tooltip]`, procs o hashes. |
437
+ | `title:` | `String` | `""` | Titulo centrado en la cabecera del marco de opciones. |
438
+ | `banner:` | `String` | `""` | Texto convertido a arte ASCII 3D superior. |
439
+ | `subtitle:` | `String` | `""` | Descripcion o subtitulo (soporta saltos de linea `\n`). |
440
+ | `search:` | `Boolean` | `false` | Activa el buscador instantaneo mientras se escribe. |
441
+ | `columns:` | `Integer` | `1` | Cantidad de columnas para distribucion en cuadricula 2D. |
442
+ | `page_size:` | `Integer` | `auto` | Maximo de filas visibles antes de activar desplazamiento con scroll. |
443
+ | `style:` | `Integer` | `19` | Estilo de marco para las opciones (1 al 20). |
444
+ | `banner_style:` | `Integer` | `3` | Estilo de marco para el banner 3D (1 al 20). |
445
+ | `font:` | `Integer` | `1` | Fuente tipografica del banner ASCII (1 al 10). |
446
+ | `image:` | `String` | `nil` | Ruta al archivo de imagen de cabecera (PNG/JPG/WEBP/GIF/BMP). |
447
+ | `image_width:` | `Integer` | `40` | Ancho en columnas para el renderizado de la imagen. |
448
+ | `divider:` | `Boolean/Int` | `true` | Lineas divisorias horizontales ajustadas al marco. |
449
+ | `center:` | `Boolean` | `true` | Centrado horizontal simetrico automatico. |
450
+
451
+ ### Metodos de Estilo `menu.set_style`
452
+
453
+ | Metodo | Argumentos | Descripcion |
454
+ |:-------|:-----------|:------------|
455
+ | `banner(color, level=2)` | `(String, Integer)` | Color del banner ASCII (soporta `"rgb"`). |
456
+ | `title(color, level=2)` | `(String, Integer)` | Color del titulo del recuadro (soporta `"rgb"`). |
457
+ | `subtitle(color, level=1)` | `(String, Integer)` | Color del texto del subtitulo (soporta `"rgb"`). |
458
+ | `divider(color, level=1)` | `(String, Integer)` | Color de las lineas divisorias (soporta `"rgb"`). |
459
+ | `border(color, level=1)` | `(String, Integer)` | Color del marco de opciones (soporta `"rgb"`). |
460
+ | `options(color, level=1)` | `(String, Integer)` | Color de las opciones inactivas (soporta `"rgb"`). |
461
+ | `focus(color, level=2)` | `(String, Integer)` | Color del cursor y opcion activa (soporta `"rgb"`). |
462
+ | `font(font_id)` | `(Integer 1..10)` | Cambia la fuente tipografica del banner. |
463
+
464
+ ### Metodos Estaticos y Modales
465
+
466
+ | Metodo | Firma | Retorno |
467
+ |:-------|:------|:--------|
468
+ | `GRmenu.checkbox` | `(items, title:, color:, style:, page_size:, preselected:)` | `Array` con los elementos marcados. |
469
+ | `GRmenu.slider` | `(prompt, min:, max:, step:, default:, unit:, color:, style:)` | `Numeric` con el valor seleccionado. |
470
+ | `GRmenu.confirm` | `(pregunta, default: true, color: "cyan", style: 3)` | `Boolean` (`true` para Si, `false` para No). |
471
+ | `GRmenu.input` | `(prompt, default: "", password: false, color: "cyan", style: 3)` | `String` ingresado por el usuario. |
472
+ | `GRmenu.image` | `(filepath, width: 40, height: nil, style: 3, color: "cyan")` | Dibuja la imagen en la terminal. |
473
+ | `GRmenu.progress` | `(total = 100, title: nil, color: "cyan", style: 3, &bloque)` | Ejecuta el bloque con la barra de progreso. |
474
+ | `GRmenu.spinner` | `(mensaje = "...", color: "cyan", delay: 0.08, &bloque)` | Ejecuta el bloque mostrando un spinner animado. |
475
+ | `GRmenu.banner` | `(texto, delay = 0, color: "magenta", style: 3, font: 1)` | Imprime texto en arte ASCII 3D. |
476
+ | `GRmenu.div` | `(long = nil, color = "blue", level = 1, char = "─")` | Imprime una linea divisoria en la consola. |
477
+ | `GRmenu.clear_screen`| `()` (Alias: `GRmenu.clr`) | Limpia la pantalla y el scrollback al instante. |
478
+ | `GRmenu.continue` | `(texto = "Presiona cualquier tecla...")` | Pausa la ejecucion hasta presionar una tecla. |
479
+ | `GRmenu.help` | `()` | Muestra la guia interactiva de documentacion en consola. |
480
+
481
+ ---
324
482
 
325
- Las contribuciones son bienvenidas. Podés abrir un [issue](https://github.com/JoseEduardoGR/GRmenu/issues) o enviar un pull request.
483
+ ## Mapa de Controles y Teclado
484
+
485
+ | Tecla / Combinacion | Contexto | Accion Realizada |
486
+ |:--------------------|:---------|:-----------------|
487
+ | `↑` (Arriba) / `k` | Menus / Checkbox | Mueve el foco hacia arriba (con salto continuo *Snake* en extremos). |
488
+ | `↓` (Abajo) / `j` | Menus / Checkbox | Mueve el foco hacia abajo. |
489
+ | `←` / `→` | Grid 2D | Salta de columna a la izquierda o derecha. |
490
+ | `Espacio` | Checkbox | Marca o desmarca la casilla del elemento actual `[X]` / `[ ]`. |
491
+ | `a` / `A` | Checkbox | Marca todos los elementos (*Select All*). |
492
+ | `n` / `N` | Checkbox | Desmarca todos los elementos (*Deselect All*). |
493
+ | `i` / `I` | Checkbox | Invierte la seleccion de todos los elementos. |
494
+ | `←` / `→` o `h` / `l`| Slider | Ajusta el valor numerico en un incremento (`step`). |
495
+ | `↑` / `↓` o `k` / `j`| Slider | Salto rapido de 5 pasos en el valor numerico. |
496
+ | `Enter` | Global | Ejecuta la accion seleccionada o confirma el formulario. |
497
+ | `q` / `Esc` | Global | Sale del menu o cancela la operacion actual. |
498
+ | `Backspace` | Buscador / Input | Borra el ultimo caracter ingresado. |
499
+ | `Ctrl+U` | Buscador / Input | Limpia todo el texto ingresado. |
326
500
 
327
501
  ---
328
502
 
329
- ## 📄 Licencia
503
+ ## Recetas y Casos de Uso del Mundo Real
504
+
505
+ ### Asistente de Instalacion de Servidores
506
+
507
+ ```ruby
508
+ require 'GRmenu'
509
+
510
+ GRmenu.clear_screen
511
+ GRmenu.banner("SETUP", 0, color: "rgb", style: 3, font: 1)
512
+
513
+ nombre = GRmenu.input("Nombre del proyecto:", default: "mi-app", color: "rgb")
514
+ puerto = GRmenu.slider("Puerto HTTP:", min: 3000, max: 9000, step: 100, default: 8080, color: "rgb")
515
+
516
+ modulos = [
517
+ ["Proxy Nginx", true, "Servidor web frontal"],
518
+ ["Base PostgreSQL", true, "Base de datos relacional"],
519
+ ["Redis Cache", false, "Acelerador de sesiones"]
520
+ ]
521
+ seleccion = GRmenu.checkbox(modulos, title: "Selecciona Modulos", color: "rgb")
522
+
523
+ if GRmenu.confirm("Deseas comenzar la instalacion ahora?", default: true, color: "rgb")
524
+ GRmenu.progress(100, title: "Instalando Componentes", color: "rgb") do |bar|
525
+ seleccion.each_with_index do |item, idx|
526
+ sleep 0.4
527
+ bar.advance(100 / seleccion.length, status: "Configurando #{item[0]}...")
528
+ end
529
+ end
530
+ puts Color.bright_green("\n-> Instalacion de '#{nombre}' completada en el puerto #{puerto}!")
531
+ end
532
+ GRmenu.continue
533
+ ```
534
+
535
+ ---
330
536
 
331
- Distribuido bajo licencia [MIT](LICENSE).
537
+ ## Licencia
332
538
 
333
- <div align="center">
539
+ Distribuido bajo licencia **MIT**. Consulta [`LICENSE`](LICENSE) para mas detalles.
334
540
 
335
- Hecho por [grcode](https://github.com/JoseEduardoGR)
541
+ Desarrollado con precision por **[grcode](https://github.com/JoseEduardoGR)**
336
542
 
337
- </div>