From ae3b7c7094a0ce9fac51853d860b2fa77206d2c8 Mon Sep 17 00:00:00 2001 From: "Mauro Rosero P." Date: Fri, 4 Apr 2025 16:04:49 -0500 Subject: [PATCH] [DOCS] Tutorial completo sobre el uso de Gum para interfaces TUI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Creado tutorial detallado sobre Gum en docs/forms-gum.md - Incluidos ejemplos prácticos de formularios, menús y selectores - Documentadas técnicas avanzadas como layouts y tablas - Añadidos ejemplos de integración con MRDevs Tools - Incluidas mejores prácticas y esquemas de personalización - Actualizado .gitignore para incluir la carpeta de documentación 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .gitignore | 2 + docs/forms-gum.md | 665 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 667 insertions(+) create mode 100644 docs/forms-gum.md diff --git a/.gitignore b/.gitignore index a55883b..91181e6 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ !sops/ !projects/ !data/ +!docs/ # Excluir el contenido de data pero mantener la carpeta data/* @@ -35,3 +36,4 @@ data/* !bin/ansible/** !inventory/** !sops/*.yaml +!docs/*.md diff --git a/docs/forms-gum.md b/docs/forms-gum.md new file mode 100644 index 0000000..29536d3 --- /dev/null +++ b/docs/forms-gum.md @@ -0,0 +1,665 @@ +# Creando Formularios Interactivos con Gum + +## Introducción + +[Gum](https://github.com/charmbracelet/gum) es una herramienta de línea de comandos desarrollada por [Charm](https://charm.sh/) que permite crear interfaces de texto (TUI) elegantes y funcionales para scripts Bash. Con Gum, puedes mejorar dramáticamente la experiencia de usuario de tus scripts de shell, añadiendo formularios interactivos, menús, estilos y más. + +Este tutorial cubre cómo utilizar Gum para crear formularios interactivos en scripts de shell dentro del entorno MRDevs Tools. + +## Requisitos Previos + +- MRDevs Tools instalado (bootstrap.sh ya instala Gum automáticamente) +- Conocimientos básicos de shell scripting + +## Instalación de Gum + +Si no tienes MRDevs Tools instalado o necesitas instalar Gum manualmente, puedes hacerlo con: + +```bash +# Verifica si gum está instalado +command -v gum > /dev/null || { + echo "Instalando gum..." + bin/bootstrap.sh +} +``` + +## Componentes Básicos de Gum + +Gum ofrece varios comandos para crear diferentes tipos de elementos de interfaz: + +| Comando | Descripción | +|---------|-------------| +| `gum style` | Da formato al texto (color, negrita, etc.) | +| `gum input` | Campo de entrada para texto | +| `gum write` | Área de texto multilínea | +| `gum confirm` | Diálogo de confirmación (Sí/No) | +| `gum choose` | Menú de selección de opciones | +| `gum filter` | Lista filtrable de opciones | +| `gum spin` | Indicador de carga con mensaje | +| `gum format` | Formatea texto (Markdown, código, etc.) | +| `gum join` | Combina salidas en layouts | +| `gum table` | Muestra datos en formato de tabla | +| `gum pager` | Visualizador de texto paginado | + +## Ejemplos Prácticos + +### 1. Formulario Básico de Registro + +Vamos a crear un formulario simple que solicite nombre, correo electrónico y contraseña: + +```bash +#!/bin/bash +# Ejemplo de formulario básico con Gum + +# Importar bibliotecas necesarias (opcional para MRDevs Tools) +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/lib/base.lib" + +# Título estilizado +echo +gum style --foreground 212 --bold --align center "Formulario de Registro" +echo + +# Solicitar información +gum style --foreground 99 "Por favor, ingresa tus datos:" +echo + +nombre=$(gum input --placeholder "Tu nombre completo" --prompt "Nombre: " --width 40) +email=$(gum input --placeholder "ejemplo@dominio.com" --prompt "Email: " --width 40) +password=$(gum input --password --placeholder "Tu contraseña segura" --prompt "Contraseña: " --width 40) + +# Confirmar datos +echo +gum style --foreground 99 "Confirma tus datos:" +echo "Nombre: $nombre" +echo "Email: $email" +echo "Contraseña: $(echo $password | sed 's/./*/g')" + +# Confirmación +echo +if gum confirm "¿Los datos son correctos?"; then + gum style --foreground 82 "✓ Usuario registrado correctamente." +else + gum style --foreground 196 "✗ Proceso cancelado." +fi +``` + +### 2. Selector de Proyecto + +Creemos un selector para elegir el tipo de proyecto a crear: + +```bash +#!/bin/bash +# Selector de tipo de proyecto + +echo +gum style --foreground 212 --bold "Selección de Tipo de Proyecto" +echo + +# Definir opciones +TIPOS=("Web Frontend" "API Backend" "Aplicación Móvil" "Biblioteca/SDK" "Base de Datos" "DevOps/Infraestructura") + +# Usar gum choose para selección +tipo_seleccionado=$(gum choose --height 10 --cursor-prefix "[ ] " --selected-prefix "[✓] " "${TIPOS[@]}") + +# Verificar que se seleccionó un tipo +if [ -n "$tipo_seleccionado" ]; then + echo + gum style --foreground 82 "Has seleccionado: $tipo_seleccionado" + + # Solicitar nombre del proyecto + echo + nombre_proyecto=$(gum input --width 40 --placeholder "mi-nuevo-proyecto" --prompt "Nombre del proyecto: ") + + # Descripción multilínea + echo + gum style "Escribe una breve descripción del proyecto:" + descripcion=$(gum write --placeholder "Describe tu proyecto aquí..." --width 60 --height 5) + + # Resumen + echo + gum style --foreground 99 --bold "Resumen del Proyecto:" + echo + echo "Tipo: $tipo_seleccionado" + echo "Nombre: $nombre_proyecto" + echo -e "Descripción:\n$descripcion" + + # Confirmación + echo + if gum confirm "¿Deseas crear este proyecto?"; then + gum spin --spinner dot --title "Creando proyecto..." -- sleep 2 + echo + gum style --foreground 82 "✓ Proyecto '$nombre_proyecto' creado con éxito." + else + echo + gum style --foreground 196 "✗ Operación cancelada." + fi +else + gum style --foreground 196 "✗ No se seleccionó ningún tipo de proyecto." +fi +``` + +### 3. Utilidad de Configuración del Sistema + +Este ejemplo muestra cómo crear una utilidad para configurar aspectos del sistema: + +```bash +#!/bin/bash +# Utilidad de configuración del sistema + +# Función para mostrar el encabezado +show_header() { + gum style \ + --foreground 212 --border double --border-foreground 99 \ + --align center --width 50 --margin "1 0" --padding "1 2" \ + "Utilidad de Configuración del Sistema" +} + +# Función para mostrar el menú principal +show_menu() { + gum style --foreground 99 "Selecciona una opción:" + gum choose --height 10 \ + "1. Configurar Red" \ + "2. Gestionar Usuarios" \ + "3. Servicios del Sistema" \ + "4. Actualizaciones" \ + "5. Salir" +} + +# Simular configuración de red +config_network() { + gum style --foreground 212 --bold "Configuración de Red" + + # Elegir tipo de conexión + tipo_red=$(gum choose "Ethernet" "WiFi" "VPN" "Volver") + + if [ "$tipo_red" = "Volver" ]; then + return + fi + + gum style "Has seleccionado: $tipo_red" + + if [ "$tipo_red" = "WiFi" ]; then + # Simulando escaneo de redes + gum spin --spinner dot --title "Escaneando redes WiFi..." -- sleep 2 + + # Elegir red WiFi + red=$(gum filter --placeholder "Buscar red..." --height 10 <<< "Red_Casa +Red_Oficina +Red_Invitados +Red_Vecino +WiFi_5G +WiFi_IoT") + + if [ -n "$red" ]; then + password=$(gum input --password --prompt "Contraseña para $red: ") + gum spin --spinner dot --title "Conectando a $red..." -- sleep 2 + gum style --foreground 82 "✓ Conectado a $red correctamente." + fi + else + gum style --foreground 99 "Esta función está en desarrollo." + fi + + gum input --placeholder "Presiona Enter para continuar..." +} + +# Función principal +main() { + clear + show_header + + while true; do + echo + opcion=$(show_menu) + + case $opcion in + "1. Configurar Red") + clear + show_header + config_network + clear + show_header + ;; + "5. Salir") + clear + gum style --foreground 82 "¡Gracias por usar la Utilidad de Configuración!" + exit 0 + ;; + *) + clear + show_header + gum style --foreground 99 "Esta función está en desarrollo." + gum input --placeholder "Presiona Enter para continuar..." + clear + show_header + ;; + esac + done +} + +# Ejecutar la aplicación +main +``` + +## Técnicas Avanzadas + +### Layouts con `gum join` + +Puedes crear layouts horizontales y verticales con `gum join`: + +```bash +# Layout horizontal con columnas +gum join --horizontal \ + "$(gum style --padding "1 2" --border normal --width 20 "Panel 1")" \ + "$(gum style --padding "1 2" --border normal --width 20 "Panel 2")" \ + "$(gum style --padding "1 2" --border normal --width 20 "Panel 3")" + +# Layout vertical con filas +gum join --vertical \ + "$(gum style --padding "1 2" --border normal --width 50 "Fila 1")" \ + "$(gum style --padding "1 2" --border normal --width 50 "Fila 2")" \ + "$(gum style --padding "1 2" --border normal --width 50 "Fila 3")" +``` + +### Tablas de Datos + +Las tablas son útiles para mostrar datos estructurados: + +```bash +# Crear una tabla +echo -e "NOMBRE\tROL\tDEPARTAMENTO\nJuan Pérez\tDesarrollador\tTecnología\nAna García\tDiseñadora\tMarketing\nCarlos López\tGerente\tAdministración" | \ +gum table --widths 20,15,20 --height 10 +``` + +### Filtrar Listas Largas + +Para buscar en listas extensas: + +```bash +# Lista con filtro de búsqueda +cat /etc/passwd | gum filter --placeholder "Buscar usuario..." --height 15 +``` + +### Personalización con Temas + +Puedes personalizar colores y estilos con variables de entorno: + +```bash +# Configurar tema +export GUM_INPUT_CURSOR_FOREGROUND="#FF5F87" +export GUM_INPUT_PROMPT_FOREGROUND="#5F87FF" +export GUM_CONFIRM_SELECTED_BACKGROUND="#5F87FF" +export GUM_CONFIRM_UNSELECTED_BACKGROUND="#FF5F87" + +# Probar con el tema personalizado +gum input --prompt "Nombre: " +gum confirm "¿Continuar?" +``` + +## Integración con MRDevs Tools + +### Template de Asistente con Gum + +Aquí hay un template para crear asistentes interactivos en MRDevs Tools: + +```bash +#!/bin/bash +#Script : asistente_ejemplo.sh +#Apps : MRDEVS TOOLS +#Description : Asistente interactivo con Gum +#Author : Tu Nombre +#Created : 2025/04/05 +#Modified : 2025/04/05 +#Version : 1.0.0 +#Use Notes : +#============================================================================== +# Derechos de Autor 2025 Mauro Rosero P. +#============================================================================== +# Este programa es software libre: usted puede redistribuirlo y/o modificarlo +# bajo los términos de la Licencia Pública Affero General de GNU tal como +# lo publica la Free Software Foundation, ya sea la versión 3 de la licencia, +# o (a su elección) cualquier versión posterior. +# +# [...] + +# Configuración inicial +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/lib/base.lib" +source "${SCRIPT_DIR}/lib/console.lib" + +# Cargar mensajes +load_messages "${SCRIPT_DIR}" "msg" "${LANG:0:2}" "head" + +# Verificar que gum esté instalado +command_installed gum +if [ $? -ne 0 ]; then + echo "Error: Gum no está instalado. Ejecutando bootstrap.sh..." + "${SCRIPT_DIR}/bootstrap.sh" + + # Verificar nuevamente + command_installed gum + if [ $? -ne 0 ]; then + echo "Error: No se pudo instalar Gum. Abortando." + exit 1 + fi +fi + +# Funciones del asistente +mostrar_titulo() { + clear + gum style \ + --foreground 212 --border double --border-foreground 99 \ + --align center --width 60 --margin "1 0" --padding "1 2" \ + "Asistente Interactivo MRDevs" +} + +mostrar_menu() { + gum style --foreground 99 "Selecciona una opción:" + gum choose --height 10 \ + "1. Opción Uno" \ + "2. Opción Dos" \ + "3. Opción Tres" \ + "4. Salir" +} + +# Flujo principal +main() { + mostrar_titulo + + while true; do + echo + opcion=$(mostrar_menu) + + case $opcion in + "1. Opción Uno") + gum style --foreground 82 "Has seleccionado la Opción Uno" + gum input --placeholder "Presiona Enter para continuar..." + mostrar_titulo + ;; + "4. Salir") + gum style --foreground 82 "¡Gracias por usar el Asistente MRDevs!" + exit 0 + ;; + *) + gum style --foreground 196 "Opción no implementada aún." + gum input --placeholder "Presiona Enter para continuar..." + mostrar_titulo + ;; + esac + done +} + +# Iniciar programa +main +``` + +### Ejemplo Práctico: Asistente de Configuración de Proyecto + +Este ejemplo muestra cómo usar Gum para crear un asistente para inicializar proyectos: + +```bash +#!/bin/bash +# Asistente de configuración de proyecto con Gum + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/lib/base.lib" + +# Asegurar que existe el directorio para guardar los proyectos +PROJECTS_DIR="$HOME/projects" +mkdir -p "$PROJECTS_DIR" + +# Función para el encabezado +show_header() { + gum style \ + --foreground "#00AAFF" --border double --border-foreground "#FF00AA" \ + --align center --width 70 --margin "1 0" --padding "1 2" \ + "🚀 Asistente de Inicialización de Proyectos 🚀" +} + +# Función para mostrar pasos del proceso +show_step() { + local step=$1 + local total=$2 + local title=$3 + + gum style \ + --foreground "#FFAA00" --bold \ + "[$step/$total] $title" + echo +} + +# Función principal +main() { + clear + show_header + + # Paso 1: Nombre del proyecto + show_step 1 5 "Nombre del Proyecto" + + project_name=$(gum input --placeholder "mi-nuevo-proyecto" --prompt "Nombre: " --width 50) + + if [ -z "$project_name" ]; then + gum style --foreground "#FF0000" "❌ El nombre del proyecto no puede estar vacío." + exit 1 + fi + + project_path="$PROJECTS_DIR/$project_name" + + if [ -d "$project_path" ]; then + overwrite=$(gum confirm "El proyecto ya existe. ¿Deseas sobrescribirlo?") + if [ $? -ne 0 ]; then + gum style --foreground "#FF0000" "Operación cancelada." + exit 0 + fi + rm -rf "$project_path" + fi + + # Paso 2: Tipo de proyecto + clear + show_header + show_step 2 5 "Tipo de Proyecto" + + project_type=$(gum choose "web" "api" "cli" "library" "mobile") + + # Paso 3: Lenguaje de programación + clear + show_header + show_step 3 5 "Lenguaje de Programación" + + languages=() + + case $project_type in + "web") + languages=("JavaScript" "TypeScript" "Python" "PHP" "Ruby") + ;; + "api") + languages=("JavaScript" "TypeScript" "Python" "Go" "Java" "Ruby") + ;; + "cli") + languages=("Python" "Go" "Rust" "C" "C++") + ;; + "library") + languages=("JavaScript" "TypeScript" "Python" "C++" "Java") + ;; + "mobile") + languages=("Kotlin" "Swift" "React Native" "Flutter") + ;; + esac + + language=$(gum choose "${languages[@]}") + + # Paso 4: Descripción + clear + show_header + show_step 4 5 "Descripción del Proyecto" + + gum style "Escribe una breve descripción del proyecto:" + description=$(gum write --placeholder "Describe tu proyecto aquí..." --width 70 --height 5) + + # Paso 5: Confirmar y crear + clear + show_header + show_step 5 5 "Confirmación" + + gum style --foreground "#00AAFF" "Resumen del Proyecto:" + echo + gum style --bold "Nombre: " --no-bold "$project_name" + gum style --bold "Tipo: " --no-bold "$project_type" + gum style --bold "Lenguaje: " --no-bold "$language" + gum style --bold "Ruta: " --no-bold "$project_path" + echo + gum style --bold "Descripción:" + echo "$description" + echo + + create=$(gum confirm "¿Crear este proyecto?") + if [ $? -ne 0 ]; then + gum style --foreground "#FF0000" "Operación cancelada." + exit 0 + fi + + # Crear proyecto + gum spin --spinner dot --title "Creando estructura del proyecto..." -- bash -c " + mkdir -p \"$project_path\" + cd \"$project_path\" + echo \"# $project_name\" > README.md + echo \"$description\" >> README.md + + # Crear estructura básica según el tipo de proyecto + case $project_type in + \"web\") + mkdir -p src/assets src/components src/styles + touch src/index.js src/styles/main.css + ;; + \"api\") + mkdir -p src/controllers src/models src/routes + touch src/app.js src/config.js + ;; + \"cli\") + mkdir -p src/commands src/utils + touch src/main.js src/config.js + ;; + \"library\") + mkdir -p src/lib tests examples + touch src/index.js + ;; + \"mobile\") + mkdir -p src/screens src/components src/assets + touch src/App.js + ;; + esac + + # Inicializar Git + git init > /dev/null 2>&1 + echo 'node_modules\n.DS_Store\n*.log' > .gitignore + git add . > /dev/null 2>&1 + git commit -m \"Initial commit\" > /dev/null 2>&1 + " + + # Mostrar resumen final + clear + show_header + + gum style --foreground "#00FF00" "✅ Proyecto creado exitosamente:" + echo + gum style --bold "Ubicación: " --no-bold "$project_path" + gum style --bold "Estructura:" + echo + find "$project_path" -type f -o -type d | grep -v ".git" | sort | sed "s|$project_path|└── proyecto|" + echo + + gum style --foreground "#00AAFF" "Siguientes pasos:" + echo + gum style "1. Navega a tu proyecto: cd $project_path" + gum style "2. Inicia el desarrollo con tu IDE favorito" + gum style "3. Consulta la documentación en el README.md" +} + +# Ejecutar programa +main +``` + +## Consejos y Mejores Prácticas + +1. **Verificación de instalación**: Siempre verifica que Gum esté instalado antes de usarlo: + ```bash + command -v gum >/dev/null 2>&1 || { echo "Gum no está instalado"; exit 1; } + ``` + +2. **Personalización de colores**: Usa variables de entorno para personalizar colores: + ```bash + export GUM_INPUT_PROMPT_FOREGROUND="#5F87FF" + ``` + +3. **Reutilización**: Crea funciones para elementos comunes: + ```bash + show_title() { + gum style --foreground 212 --bold --align center "$1" + } + ``` + +4. **Validación de entrada**: Siempre valida las entradas del usuario: + ```bash + if [[ -z "$input" ]]; then + gum style --foreground 196 "Error: Campo requerido" + fi + ``` + +5. **Confirmaciones**: Usa confirmaciones antes de acciones irreversibles: + ```bash + if gum confirm "¿Estás seguro?"; then + # acción peligrosa + fi + ``` + +6. **Spinners para operaciones largas**: Muestra progreso durante operaciones que toman tiempo: + ```bash + gum spin --spinner dot --title "Procesando..." -- sleep 3 + ``` + +7. **Anchura consistente**: Mantén una anchura consistente en tus interfaces: + ```bash + WIDTH=50 + gum style --width $WIDTH "Texto 1" + gum input --width $WIDTH + ``` + +## Esquemas de Color y Estilos + +Gum soporta colores hexadecimales y códigos ANSI: + +```bash +# Colores hexadecimales +gum style --foreground "#FF5F87" "Texto en rosa" + +# Colores ANSI +gum style --foreground 212 "Texto en púrpura" +``` + +Estilos de texto disponibles: +- `--bold`: Texto en negrita +- `--italic`: Texto en cursiva +- `--strikethrough`: Texto tachado +- `--underline`: Texto subrayado + +Estilos de borde: +- `--border normal`: Borde simple +- `--border double`: Borde doble +- `--border rounded`: Borde redondeado +- `--border thick`: Borde grueso + +## Conclusión + +Gum es una herramienta poderosa para elevar la experiencia de usuario en tus scripts de shell. Permite crear interfaces atractivas y funcionales sin salir de la terminal. En MRDevs Tools, Gum está integrado y listo para usarse, lo que te permite crear flujos de trabajo más intuitivos y profesionales. + +## Recursos Adicionales + +- [Documentación oficial de Gum](https://github.com/charmbracelet/gum) +- [Charm.sh](https://charm.sh/) - Creadores de Gum y otras herramientas TUI +- [Lip Gloss](https://github.com/charmbracelet/lipgloss) - Biblioteca para estilos en Go (base de Gum) +- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - Framework TUI en Go (usado por Gum) + +--- + +Creado por Cortana Rosero One para MRDevs Tools. +Última actualización: 2025/04/04 \ No newline at end of file