grmenu 4.1.0 → 5.0.0

data/grmenu/interactive.rb

@@ -0,0 +1,1002 @@
+# frozen_string_literal: true
+
+class GRmenu
+  # Atributos de configuración y estado del menú interactivo
+  attr_accessor :functions, :title, :subtitle, :banner, :banner_style, :divider,
+                :index, :style_config, :center, :page_size, :search, :columns,
+                :query, :image, :image_width
+
+  # Alias de compatibilidad hacia atrás
+  alias_method :options, :functions
+  alias_method :options=, :functions=
+  alias_method :selected_index, :index
+  alias_method :selected_index=, :index=
+  alias_method :SetStyle, :style_config
+  alias_method :set_style, :style_config
+  alias_method :description, :subtitle
+  alias_method :description=, :subtitle=
+
+  # Retorna el prefijo configurado para las descripciones de opciones (por defecto '[i]')
+  def desc_prefix
+    @desc_prefix || @style_config&.desc_prefix || SetStyle.desc_prefix
+  end
+
+  # Modifica dinámicamente el prefijo de las descripciones
+  def desc_prefix=(val)
+    @desc_prefix = val.to_s
+    @style_config&.desc_prefix(val)
+  end
+  alias_method :prefix, :desc_prefix
+  alias_method :prefix=, :desc_prefix=
+  alias_method :description_prefix, :desc_prefix
+  alias_method :description_prefix=, :desc_prefix=
+
+  # Accesores directos a los catálogos y datasets cargados desde JSON
+  def self.STYLES; STYLES; end
+  def self.COLORS; COLORS; end
+  def self.BORDERS; BORDERS; end
+  def self.FONTS; FONTS; end
+  def self.FONT; FONT_1; end
+
+  class << self
+    # Constructor conveniente para instanciar un menú organizado por pestañas.
+    #
+    # @param tabs_hash [Hash] Diccionario donde las claves son los nombres de pestañas y los valores son listas de acciones.
+    # @return [GRmenu] Instancia del menú configurada con pestañas.
+    def tabs(tabs_hash, *args, **kwargs)
+      new([], *args, tabs: tabs_hash, **kwargs)
+    end
+  end
+
+  # Inicializa una nueva instancia de menú interactivo.
+  #
+  # Puede configurarse mediante argumentos nominales o posicionales, así como
+  # heredar estilos globales o valores predeterminados de SetStyle.
+  #
+  # @param functions [Array, Hash] Lista de opciones ejecutables o Hash de pestañas.
+  # @param positional_arguments [Array] Argumentos posicionales opcionales: [title, style].
+  # @param title [String, nil] Título del menú mostrado en la parte superior.
+  # @param banner [String, nil] Texto para banner o logo en ASCII 3D.
+  # @param subtitle [String, nil] Subtítulo o texto descriptivo general.
+  # @param description [String, nil] Alias de subtítulo.
+  # @param divider [Boolean, Integer, nil] Si se dibuja línea divisoria tras el banner/subtítulo.
+  # @param style [Integer, nil] Estilo de borde del menú (1 al 19).
+  # @param banner_style [Integer, nil] Estilo de borde del banner (1 al 12).
+  # @param center [Boolean] Centra horizontalmente el menú en la ventana de la terminal.
+  # @param font [Integer, nil] Fuente tipográfica ASCII para el banner (1 a 11).
+  # @param page_size [Integer, nil] Número máximo de opciones visibles en pantalla.
+  # @param search [Boolean] Habilita búsqueda y filtrado en tiempo real.
+  # @param columns [Integer] Número de columnas de opciones para mostrar en cuadrícula.
+  # @param image [String, nil] Ruta a un archivo PNG para renderizarlo con caracteres de bloques.
+  # @param image_width [Integer, nil] Ancho deseado de la imagen renderizada.
+  # @param mouse [Boolean, nil] Habilita captura de eventos de clic y rueda del ratón.
+  # @param tabs [Hash, nil] Diccionario de pestañas si no se pasó en functions.
+  # @param desc_prefix [String, nil] Prefijo para la descripción inferior (ej: "[i]").
+  # @param animate [String, Symbol, Boolean, nil] Animación de entrada o continua (:rainbow, :chroma, :rgb, :fade, :diagonal, :linear, :chromatic).
+  def initialize(functions = [], *positional_arguments, title: nil, banner: nil, subtitle: nil, description: nil, divider: nil, style: nil, banner_style: nil, center: true, font: nil, page_size: nil, search: false, columns: 1, image: nil, image_width: nil, mouse: nil, tabs: nil, active_tab_color: nil, tab_color: nil, desc_prefix: nil, prefix: nil, border: nil, border_color: nil, options_color: nil, focus_color: nil, title_color: nil, banner_color: nil, subtitle_color: nil, divider_color: nil, animate: nil, **keyword_arguments)
+    # Detectamos si se pasaron pestañas en el argumento tabs o functions
+    tabs_data = tabs || keyword_arguments[:tabs] || (functions.is_a?(Hash) ? functions : nil)
+    if tabs_data.is_a?(Hash) && !tabs_data.empty?
+      @tabs = tabs_data.keys.map(&:to_s)
+      @tab_contents = tabs_data.transform_keys(&:to_s)
+      @active_tab_idx = 0
+      @functions = @tab_contents[@tabs[@active_tab_idx]] || []
+    else
+      @tabs = nil
+      @tab_contents = nil
+      @active_tab_idx = nil
+      @functions = functions.is_a?(Array) ? functions : Array(functions)
+    end
+
+    pos_title = positional_arguments[0]
+    pos_style = positional_arguments[1]
+
+    @title        = (title || pos_title || keyword_arguments[:title] || "").to_s
+    @banner       = (banner || keyword_arguments[:banner] || "").to_s
+    @subtitle     = (subtitle || description || keyword_arguments[:subtitle] || keyword_arguments[:description] || "").to_s
+    @divider      = divider.nil? ? (!@banner.empty? || !@subtitle.empty?) : divider
+
+    theme_menu_sec = (@@global_theme.is_a?(Hash) && @@global_theme.dig(:sections, 'menu')) || {}
+    th_style       = theme_menu_sec['style']&.to_i
+    th_bstyle      = theme_menu_sec['banner_style']&.to_i
+
+    @style        = (style || pos_style || keyword_arguments[:style] || th_style || 19).to_i
+    @banner_style = (banner_style || keyword_arguments[:banner_style] || th_bstyle || 3).to_i
+    @center       = center.nil? ? (theme_menu_sec.key?('center') ? (theme_menu_sec['center'].to_s != 'false') : true) : center
+    @page_size    = (page_size || keyword_arguments[:page_size])&.to_i
+    @search       = search || keyword_arguments[:search] || false
+    @columns      = [(columns || keyword_arguments[:columns] || 1).to_i, 1].max
+    @image        = image || keyword_arguments[:image]
+    @image_width  = (image_width || keyword_arguments[:image_width])&.to_i
+    @animate      = (animate || keyword_arguments[:animate] || (@@global_theme.is_a?(Hash) && @@global_theme.dig(:sections, 'menu', 'animate')) || false).to_s
+
+    # Configuración de soporte para ratón
+    m_val = mouse.nil? ? keyword_arguments[:mouse] : mouse
+    if m_val.nil?
+      @mouse = theme_menu_sec.key?('mouse') ? (theme_menu_sec['mouse'].to_s != 'false') : true
+    else
+      @mouse = (m_val == true || m_val.to_s == 'true')
+    end
+
+    tabs_theme_sec = (@@global_theme.is_a?(Hash) && @@global_theme.dig(:sections, "tabs")) || {}
+    @active_tab_color = (active_tab_color || keyword_arguments[:active_tab_color] || tabs_theme_sec["active_tab"] || tabs_theme_sec["active_tab_color"] || "yellow").to_s
+    @tab_color        = (tab_color || keyword_arguments[:tab_color] || tabs_theme_sec["tab_color"] || tabs_theme_sec["inactive_tab"] || tabs_theme_sec["color"] || "gray").to_s
+
+    @query        = String.new("")
+    @index        = 0
+    @rgb_tick     = 0.0
+
+    # Estado de navegación en submenús anidados
+    @level          = 0
+    @open_level     = 0
+    @sub_index_1    = 0
+    @sub_index_2    = 0
+    @sub_1_hit_map  = {}
+    @sub_2_hit_map  = {}
+    @sub_1_col_rng  = nil
+    @sub_2_col_rng  = nil
+
+    @active_panel   = :main
+    @sub_index      = 0
+    @submenu_open   = false
+
+    # Registro de áreas activas para eventos de ratón
+    @row_hit_map    = {}
+    @tab_ranges     = {}
+    @tabs_row       = nil
+    @up_arrow_row   = nil
+    @down_arrow_row = nil
+    @sub_hit_map    = {}
+
+    @cached_image_lines = nil
+    @cached_image_cols  = nil
+
+    # Resolución del prefijo y fuente con prioridad estricta: SetStyle explícito > argumento directo > tema > por defecto
+    init_font = font || keyword_arguments[:font] || keyword_arguments[:font_style] || SetStyle.font || 1
+    raw_pfx   = desc_prefix || prefix || keyword_arguments[:desc_prefix] || keyword_arguments[:prefix] || keyword_arguments[:description_prefix]
+    @desc_prefix = raw_pfx.to_s unless raw_pfx.nil?
+    init_pfx  = @desc_prefix || (@@global_theme.is_a?(Hash) && (@@global_theme.dig(:sections, 'menu', 'desc_prefix') || @@global_theme.dig(:sections, 'menu', 'prefix'))) || SetStyle.desc_prefix || "[i]"
+
+    @style_config = SetStyle.new(
+      border:   SetStyle.border.dup,
+      options:  SetStyle.options.dup,
+      focus:    SetStyle.focus.dup,
+      title:    SetStyle.title.dup,
+      banner:   SetStyle.banner.dup,
+      subtitle: SetStyle.subtitle.dup,
+      divider:  SetStyle.divider.dup,
+      font:     init_font,
+      desc_prefix: init_pfx
+    )
+    @style_config.mark_explicit(:font) if font || keyword_arguments[:font] || keyword_arguments[:font_style]
+    @style_config.mark_explicit(:desc_prefix) unless raw_pfx.nil?
+
+    # Aplicamos estilos directos si fueron provistos en la llamada new()
+    if border || border_color || keyword_arguments[:border] || keyword_arguments[:border_color]
+      b_c, b_l = self.class.extract_color_and_level(border || border_color || keyword_arguments[:border] || keyword_arguments[:border_color], 1)
+      @style_config.border(b_c, b_l)
+    end
+    if options_color || keyword_arguments[:options_color] || keyword_arguments[:options]
+      o_c, o_l = self.class.extract_color_and_level(options_color || keyword_arguments[:options_color] || keyword_arguments[:options], 1)
+      @style_config.options(o_c, o_l)
+    end
+    if focus_color || keyword_arguments[:focus_color] || keyword_arguments[:focus]
+      f_c, f_l = self.class.extract_color_and_level(focus_color || keyword_arguments[:focus_color] || keyword_arguments[:focus], 2)
+      @style_config.focus(f_c, f_l)
+    end
+    if title_color || keyword_arguments[:title_color]
+      t_c, t_l = self.class.extract_color_and_level(title_color || keyword_arguments[:title_color], 2)
+      @style_config.title(t_c, t_l)
+    end
+    if banner_color || keyword_arguments[:banner_color]
+      bn_c, bn_l = self.class.extract_color_and_level(banner_color || keyword_arguments[:banner_color], 2)
+      @style_config.banner(bn_c, bn_l)
+    end
+    if subtitle_color || keyword_arguments[:subtitle_color]
+      s_c, s_l = self.class.extract_color_and_level(subtitle_color || keyword_arguments[:subtitle_color], 1)
+      @style_config.subtitle(s_c, s_l)
+    end
+    if divider_color || keyword_arguments[:divider_color]
+      d_c, d_l = self.class.extract_color_and_level(divider_color || keyword_arguments[:divider_color], 1)
+      @style_config.divider(d_c, d_l)
+    end
+  end
+
+  # Devuelve la lista de índices de @functions que coinciden con el término de búsqueda actual.
+  #
+  # @return [Array<Integer>]
+  def current_matching_indices
+    if @search && !@query.empty?
+      indices = []
+      @functions.each_with_index do |func, idx|
+        name = extract_name_from_action(func)
+        indices << idx if name.downcase.include?(@query.downcase)
+      end
+      indices
+    else
+      (0...@functions.length).to_a
+    end
+  end
+
+  # Desplaza el cursor de selección una fila hacia arriba.
+  # En menús multi-columna salta exactamente el ancho de la columna hacia arriba.
+  def move_up
+    matching = current_matching_indices
+    return @index if matching.empty?
+    cols = @columns
+    pos = matching.index(@index) || 0
+    if cols <= 1
+      new_pos = (pos - 1) % matching.length
+    else
+      new_pos = pos - cols
+      if new_pos < 0
+        new_pos = pos
+        while (new_pos + cols) < matching.length
+          new_pos += cols
+        end
+      end
+    end
+    @index = matching[new_pos]
+  end
+  alias_method :_up, :move_up
+
+  # Desplaza el cursor de selección una fila hacia abajo.
+  def move_down
+    matching = current_matching_indices
+    return @index if matching.empty?
+    cols = @columns
+    pos = matching.index(@index) || 0
+    if cols <= 1
+      new_pos = (pos + 1) % matching.length
+    else
+      new_pos = pos + cols
+      if new_pos >= matching.length
+        new_pos = pos % cols
+      end
+    end
+    @index = matching[new_pos]
+  end
+  alias_method :_down, :move_down
+
+  # Desplaza el cursor de selección una columna hacia la izquierda.
+  def move_left
+    matching = current_matching_indices
+    return @index if matching.empty?
+    cols = @columns
+    pos = matching.index(@index) || 0
+    if cols <= 1
+      new_pos = (pos - 1) % matching.length
+    else
+      if (pos % cols) == 0
+        new_pos = [pos + (cols - 1), matching.length - 1].min
+      else
+        new_pos = pos - 1
+      end
+    end
+    @index = matching[new_pos]
+  end
+
+  # Desplaza el cursor de selección una columna hacia la derecha.
+  def move_right
+    matching = current_matching_indices
+    return @index if matching.empty?
+    cols = @columns
+    pos = matching.index(@index) || 0
+    if cols <= 1
+      new_pos = (pos + 1) % matching.length
+    else
+      if (pos % cols) == (cols - 1) || pos == (matching.length - 1)
+        new_pos = pos - (pos % cols)
+      else
+        new_pos = pos + 1
+      end
+    end
+    @index = matching[new_pos]
+  end
+
+  # Configura estilos a partir de una cadena con sintaxis de hoja de estilos GR.
+  #
+  # Respeta las propiedades que hayan sido configuradas explícitamente mediante SetStyle,
+  # garantizando que la configuración programática siempre tiene la máxima prioridad.
+  #
+  # @param css_content [String, nil] Bloque de texto con directivas <<menu ... >>
+  # @return [self, Integer] La instancia para encadenar llamadas, o el estilo actual si no se pasan argumentos.
+  def style(css_content = nil)
+    return @style if css_content.nil?
+    parsed = self.class.parse_config_text(css_content)
+    menu_cfg = ((parsed[:sections] && parsed[:sections]["menu"]) || {}).merge(parsed[:global] || {})
+
+    if menu_cfg["style"]
+      @style = menu_cfg["style"].to_i
+      @border_config = BORDERS[@style] || BORDERS[3]
+    end
+    @banner_style = menu_cfg["banner_style"].to_i if menu_cfg["banner_style"]
+    @animate      = menu_cfg["animate"].to_s if menu_cfg["animate"]
+    @center       = (menu_cfg["center"].to_s != "false") if menu_cfg.key?("center")
+
+    # Los colores de CSS solo se aplican si la propiedad no fue definida explícitamente en SetStyle
+    if (menu_cfg["border"] || menu_cfg["border_color"]) && !@style_config.explicitly_set?(:border)
+      c, l = self.class.extract_color_and_level(menu_cfg["border"] || menu_cfg["border_color"], 1)
+      @style_config.border(c, l, from_css: true)
+    end
+    if (menu_cfg["options"] || menu_cfg["options_color"]) && !@style_config.explicitly_set?(:options)
+      c, l = self.class.extract_color_and_level(menu_cfg["options"] || menu_cfg["options_color"], 1)
+      @style_config.options(c, l, from_css: true)
+    end
+    if (menu_cfg["focus"] || menu_cfg["focus_color"]) && !@style_config.explicitly_set?(:focus)
+      c, l = self.class.extract_color_and_level(menu_cfg["focus"] || menu_cfg["focus_color"], 2)
+      @style_config.focus(c, l, from_css: true)
+    end
+    if (menu_cfg["title"] || menu_cfg["title_color"]) && !@style_config.explicitly_set?(:title)
+      c, l = self.class.extract_color_and_level(menu_cfg["title"] || menu_cfg["title_color"], 2)
+      @style_config.title(c, l, from_css: true)
+    end
+    if (menu_cfg["banner"] || menu_cfg["banner_color"]) && !@style_config.explicitly_set?(:banner)
+      c, l = self.class.extract_color_and_level(menu_cfg["banner"] || menu_cfg["banner_color"], 2)
+      @style_config.banner(c, l, from_css: true)
+    end
+    if (menu_cfg["subtitle"] || menu_cfg["subtitle_color"]) && !@style_config.explicitly_set?(:subtitle)
+      c, l = self.class.extract_color_and_level(menu_cfg["subtitle"] || menu_cfg["subtitle_color"], 1)
+      @style_config.subtitle(c, l, from_css: true)
+    end
+    if (menu_cfg["divider"] || menu_cfg["divider_color"]) && !@style_config.explicitly_set?(:divider)
+      c, l = self.class.extract_color_and_level(menu_cfg["divider"] || menu_cfg["divider_color"], 1)
+      @style_config.divider(c, l, from_css: true)
+    end
+    if (menu_cfg["desc_prefix"] || menu_cfg["description_prefix"] || menu_cfg["prefix"]) && !@style_config.explicitly_set?(:desc_prefix)
+      @style_config.desc_prefix(menu_cfg["desc_prefix"] || menu_cfg["description_prefix"] || menu_cfg["prefix"], from_css: true)
+    end
+    if menu_cfg["font"] && !@style_config.explicitly_set?(:font)
+      @style_config.font(menu_cfg["font"].to_i, from_css: true)
+    end
+
+    @mouse = (menu_cfg["mouse"].to_s == "true") if menu_cfg.key?("mouse")
+
+    if parsed[:sections] && parsed[:sections]["tabs"]
+      tabs_sec = parsed[:sections]["tabs"]
+      @active_tab_color = tabs_sec["active_tab"] || tabs_sec["active_tab_color"] || @active_tab_color if (tabs_sec["active_tab"] || tabs_sec["active_tab_color"])
+      @tab_color        = tabs_sec["tab_color"] || tabs_sec["inactive_tab"] || tabs_sec["color"] || @tab_color if (tabs_sec["tab_color"] || tabs_sec["inactive_tab"] || tabs_sec["color"])
+    end
+
+    self
+  end
+
+  # Setter para style que acepta tanto un entero de estilo como una hoja de estilos completa.
+  def style=(val)
+    if val.is_a?(String) && (val.include?("::") || val.include?("<<") || val.include?("@theme"))
+      style(val)
+    else
+      @style = val.to_i
+      @border_config = BORDERS[@style] || BORDERS[3]
+    end
+  end
+
+  # Exporta la configuración visual y colores actuales del menú a un archivo .gr.
+  #
+  # @param path [String, nil] Ruta de salida. Si es nil, infiere el nombre del archivo llamador.
+  # @return [String] Ruta final del archivo generado.
+  def export_config(path = nil)
+    if path.nil?
+      caller_loc = caller_locations.find { |c| !c.path.include?(__FILE__) }
+      base = caller_loc ? caller_loc.path.sub(/\.rb$/, '') : "theme"
+      path = "#{base}.gr"
+    end
+
+    b_cfg  = @style_config&.border   || SetStyle.border
+    t_cfg  = @style_config&.title    || SetStyle.title
+    f_cfg  = @style_config&.focus    || SetStyle.focus
+    o_cfg  = @style_config&.options  || SetStyle.options
+    bn_cfg = @style_config&.banner   || SetStyle.banner
+    s_cfg  = @style_config&.subtitle || SetStyle.subtitle
+    d_cfg  = @style_config&.divider  || SetStyle.divider
+    dp_val = @style_config&.desc_prefix || SetStyle.desc_prefix
+
+    lines = ["GRmenu::config<-1->", ""]
+    lines << "@theme:: \"#{File.basename(path, '.gr').capitalize}\""
+    lines << "@author:: \"grcode\""
+    lines << "@version:: \"1.0\""
+    lines << ""
+    lines << "<<menu"
+    lines << "  style:: #{@style || 3}"
+    lines << "  banner_style:: #{@banner_style || 3}"
+    lines << "  font:: #{@style_config&.font || SetStyle.font}"
+    lines << "  animate:: #{@animate || 'rgb'}"
+    lines << "  center:: #{@center.nil? ? true : @center}"
+    lines << "  desc_prefix:: #{dp_val}"
+    lines << "  mouse:: #{@mouse}" if @mouse
+    lines << "  border:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  title:: #{t_cfg[:color]}:#{t_cfg[:level]}"
+    lines << "  focus:: #{f_cfg[:color]}:#{f_cfg[:level]}"
+    lines << "  options:: #{o_cfg[:color]}:#{o_cfg[:level]}"
+    lines << "  banner:: #{bn_cfg[:color]}:#{bn_cfg[:level]}"
+    lines << "  subtitle:: #{s_cfg[:color]}:#{s_cfg[:level]}"
+    lines << "  divider:: #{d_cfg[:color]}:#{d_cfg[:level]}"
+    lines << ">>"
+    lines << ""
+    lines << "<<submenu"
+    lines << "  style:: #{@style || 3}"
+    lines << "  border:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  focus:: #{f_cfg[:color]}:#{f_cfg[:level]}"
+    lines << "  options:: #{o_cfg[:color]}:#{o_cfg[:level]}"
+    lines << ">>"
+    lines << ""
+    lines << "<<tabs"
+    lines << "  active_tab:: #{@active_tab_color || 'yellow'}:2"
+    lines << "  tab_color:: #{@tab_color || 'gray'}:1"
+    lines << ">>"
+    lines << ""
+    lines << "<<input"
+    lines << "  style:: 3"
+    lines << "  border_color:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  title_color:: #{t_cfg[:color]}:#{t_cfg[:level]}"
+    lines << "  label_color:: white:1"
+    lines << ">>"
+    lines << ""
+    lines << "<<table"
+    lines << "  style:: #{@style || 3}"
+    lines << "  header_color:: yellow:2"
+    lines << "  border_color:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  selected_row:: #{f_cfg[:color]}:#{f_cfg[:level]}"
+    lines << "  row_color:: white:1"
+    lines << "  zebra_striping:: true"
+    lines << ">>"
+    lines << ""
+    lines << "<<card"
+    lines << "  style:: 7"
+    lines << "  border_color:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  title_color:: #{t_cfg[:color]}:#{t_cfg[:level]}"
+    lines << "  content_color:: white:1"
+    lines << ">>"
+    lines << ""
+    lines << "<<slider"
+    lines << "  style:: #{@style || 3}"
+    lines << "  color:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  fill_char:: █"
+    lines << "  empty_char:: ░"
+    lines << ">>"
+    lines << ""
+    lines << "<<checkbox"
+    lines << "  style:: #{@style || 3}"
+    lines << "  color:: #{b_cfg[:color]}:#{b_cfg[:level]}"
+    lines << "  checked_mark:: [X]"
+    lines << "  unchecked_mark:: [ ]"
+    lines << ">>"
+    lines << ""
+    File.write(path, lines.join("\n") + "\n")
+    path
+  end
+  alias_method :export_theme, :export_config
+
+  # Inicia el ciclo interactivo del menú en la terminal.
+  #
+  # Muestra las opciones, procesa pulsaciones de teclado y clics del ratón,
+  # redibuja animaciones si están activas y ejecuta la acción elegida.
+  #
+  # @param size_max [Integer] Ancho mínimo o sugerido de la caja.
+  # @param min_width [Integer, nil] Alias de ancho mínimo.
+  # @return [Object, nil] El resultado de la acción ejecutada o nil si se canceló.
+  def draw(size_max: 20, min_width: nil)
+    # Soporte para exportación rápida vía argumento en línea de comandos (-theme o -ex)
+    if ARGV.any? { |a| ["-theme", "--theme", "-ex", "--export-theme"].include?(a.to_s.downcase) }
+      out_idx = ARGV.index { |a| ["-o", "--out", "--output"].include?(a.to_s.downcase) }
+      target_file = out_idx ? ARGV[out_idx + 1] : "tema_exportado.gr"
+      export_config(target_file)
+      Kernel.puts Color.bright_green("[OK] Tema exportado exitosamente a: #{target_file}")
+      exit(0)
+    end
+
+    target_width = min_width || size_max || 20
+    action_to_execute = nil
+
+    self.class.enable_windows_vt
+    $stdout.sync = true
+
+    is_tty = $stdin.respond_to?(:tty?) && $stdin.tty?
+
+    begin
+      Kernel.print("#{HIDE_CURSOR}#{CLEAR_SCREEN_SEQUENCE}")
+      Kernel.print(ENABLE_MOUSE) if @mouse
+      $stdout.flush
+
+      # Si hay una transición de entrada configurada (:diagonal, :linear, :fade, :rainbow, :chroma, :rgb, :chromatic, :cromatico)
+      intro_anim = @animate.to_s.downcase
+      if ["diagonal", "linear", "fade", "rainbow", "chroma", "rgb", "chromatic", "cromatico"].include?(intro_anim)
+        intro_lines = render_lines(target_width)
+        self.class.animate_render(intro_lines, @animate)
+      end
+
+      if is_tty
+        $stdin.raw do |raw_input_stream|
+          action_to_execute = run_interactive_loop(raw_input_stream, target_width)
+        end
+      else
+        action_to_execute = run_interactive_loop($stdin, target_width)
+      end
+    ensure
+      # Siempre restaurar el ratón y el cursor para no dejar la terminal corrupta
+      Kernel.print(DISABLE_MOUSE) if @mouse
+      Kernel.print(SHOW_CURSOR)
+      $stdout.flush
+    end
+
+    if action_to_execute
+      Kernel.print(CLEAR_SCREEN_SEQUENCE)
+      $stdout.flush
+      execute_action(action_to_execute)
+    else
+      Kernel.print(CLEAR_SCREEN_SEQUENCE)
+      $stdout.flush
+    end
+  rescue Interrupt
+    # Manejo limpio al interrumpir con Ctrl+C
+    Kernel.print(DISABLE_MOUSE) if @mouse
+    Kernel.print("#{SHOW_CURSOR}#{CLEAR_SCREEN_SEQUENCE}")
+    $stdout.flush
+    nil
+  end
+
+  private
+
+  # Dibuja un solo cuadro del menú en la posición de inicio del cursor (CURSOR_HOME)
+  def draw_frame(target_width)
+    lines = render_lines(target_width)
+    buffer = String.new(CURSOR_HOME)
+    lines.each_with_index do |line, idx|
+      buffer << line << CLEAR_TO_EOL
+      buffer << "\r\n" if idx < lines.length - 1
+    end
+    buffer << CLEAR_TO_EOS
+    Kernel.print(buffer)
+    $stdout.flush
+  end
+
+  # Bucle interactivo principal: escucha teclas, eventos de ratón y actualiza animación
+  def run_interactive_loop(input_stream, target_width)
+    matching = current_matching_indices
+    @index = matching.first || 0 unless matching.include?(@index)
+    @rgb_tick = 0.0
+    draw_frame(target_width)
+
+    animating = has_active_animation?
+
+    while true
+      # Si hay animación continua (RGB, Chroma, Cromático), esperamos con select no bloqueante
+      if animating
+        ready = false
+        if input_stream.respond_to?(:to_io) || input_stream.is_a?(IO)
+          begin
+            select_res = IO.select([input_stream], nil, nil, 0.035)
+            ready = true if select_res && select_res[0] && !select_res[0].empty?
+          rescue StandardError
+            ready = true
+          end
+        else
+          ready = true
+        end
+
+        unless ready
+          @rgb_tick += 0.08
+          draw_frame(target_width)
+          next
+        end
+      end
+
+      key = read_single_key(input_stream)
+      break if key.nil? || key == "\x03" || key == "\x04"
+
+      # Evento de ratón en formato SGR: \e[<Btn;Col;Row(M|m)
+      if key =~ /\A\e\[<(\d+);(\d+);(\d+)([Mm])\z/
+        btn = $1.to_i
+        col = $2.to_i
+        row = $3.to_i
+        act = $4
+
+        # Rueda del ratón hacia arriba (btn 64)
+        if btn == 64
+          if @open_level >= 2 && @sub_2_col_rng && @sub_2_col_rng.cover?(col) && is_submenu_item?(@functions[@index])
+            s1_acts = get_submenu_actions(@functions[@index])
+            s2_acts = get_submenu_actions(s1_acts[@sub_index_1]) if s1_acts
+            @sub_index_2 = (@sub_index_2 - 1) % s2_acts.length if s2_acts && !s2_acts.empty?
+            @level = 2
+          elsif @open_level >= 1 && @sub_1_col_rng && @sub_1_col_rng.cover?(col) && is_submenu_item?(@functions[@index])
+            s1_acts = get_submenu_actions(@functions[@index])
+            @sub_index_1 = (@sub_index_1 - 1) % s1_acts.length if s1_acts && !s1_acts.empty?
+            @sub_index_2 = 0
+            @level = 1
+          else
+            move_up
+            @sub_index_1 = 0
+            @sub_index_2 = 0
+            @level = 0
+          end
+          draw_frame(target_width)
+          next
+        # Rueda del ratón hacia abajo (btn 65)
+        elsif btn == 65
+          if @open_level >= 2 && @sub_2_col_rng && @sub_2_col_rng.cover?(col) && is_submenu_item?(@functions[@index])
+            s1_acts = get_submenu_actions(@functions[@index])
+            s2_acts = get_submenu_actions(s1_acts[@sub_index_1]) if s1_acts
+            @sub_index_2 = (@sub_index_2 + 1) % s2_acts.length if s2_acts && !s2_acts.empty?
+            @level = 2
+          elsif @open_level >= 1 && @sub_1_col_rng && @sub_1_col_rng.cover?(col) && is_submenu_item?(@functions[@index])
+            s1_acts = get_submenu_actions(@functions[@index])
+            @sub_index_1 = (@sub_index_1 + 1) % s1_acts.length if s1_acts && !s1_acts.empty?
+            @sub_index_2 = 0
+            @level = 1
+          else
+            move_down
+            @sub_index_1 = 0
+            @sub_index_2 = 0
+            @level = 0
+          end
+          draw_frame(target_width)
+          next
+        # Clic izquierdo del ratón (btn 0, act 'M')
+        elsif btn == 0 && act == "M"
+          # Clic sobre la barra de pestañas
+          if @tabs && !@tabs.empty? && @tabs_row && row == @tabs_row
+            clicked_tab = @tab_ranges.find { |_idx, rng| rng.cover?(col) }
+            if clicked_tab
+              @active_tab_idx = clicked_tab[0]
+              @functions = @tab_contents[@tabs[@active_tab_idx]] || []
+              @index = 0
+              @level = 0
+              @open_level = 0
+              @sub_index_1 = 0
+              @sub_index_2 = 0
+              @active_panel = :main
+              @submenu_open = false
+              draw_frame(target_width)
+              next
+            end
+          end
+
+          # Clic en flecha superior de scroll
+          if @up_arrow_row && row == @up_arrow_row
+            move_up
+            draw_frame(target_width)
+            next
+          end
+
+          # Clic en flecha inferior de scroll
+          if @down_arrow_row && row == @down_arrow_row
+            move_down
+            draw_frame(target_width)
+            next
+          end
+
+          # Clic dentro de submenú nivel 2
+          if @open_level >= 2 && @sub_2_col_rng && @sub_2_col_rng.cover?(col) && @sub_2_hit_map[row]
+            s2_clicked = @sub_2_hit_map[row]
+            s1_acts = get_submenu_actions(@functions[@index])
+            s2_acts = get_submenu_actions(s1_acts[@sub_index_1]) if s1_acts
+            if s2_acts && s2_clicked < s2_acts.length
+              @level = 2
+              @sub_index_2 = s2_clicked
+              return s2_acts[s2_clicked]
+            end
+          end
+
+          # Clic dentro de submenú nivel 1
+          if @open_level >= 1 && @sub_1_col_rng && @sub_1_col_rng.cover?(col) && @sub_1_hit_map[row]
+            s1_clicked = @sub_1_hit_map[row]
+            s1_acts = get_submenu_actions(@functions[@index])
+            if s1_acts && s1_clicked < s1_acts.length
+              target_action = s1_acts[s1_clicked]
+              @level = 1
+              @sub_index_1 = s1_clicked
+              if is_submenu_item?(target_action)
+                @open_level = 2
+                @level = 2
+                @sub_index_2 = 0
+                draw_frame(target_width)
+                next
+              else
+                return target_action
+              end
+            end
+          end
+
+          # Clic sobre una opción de la lista principal
+          if @row_hit_map && @row_hit_map[row]
+            hit = @row_hit_map[row]
+            x_in_box = col - hit[:margin_left]
+            if x_in_box > 0 && (hit[:total_w].nil? || x_in_box <= hit[:total_w])
+              c_idx = [[((x_in_box - 2) / ([hit[:col_w], 1].max + 2)).to_i, 0].max, hit[:cols] - 1].min
+              clicked_item = hit[:row_indices][c_idx]
+              if clicked_item
+                @index = clicked_item
+                if is_submenu_item?(@functions[clicked_item])
+                  @open_level = 1
+                  @level = 1
+                  @sub_index_1 = 0
+                  @sub_index_2 = 0
+                  @active_panel = :sub
+                  @submenu_open = true
+                  draw_frame(target_width)
+                  next
+                else
+                  return @functions[clicked_item]
+                end
+              end
+            end
+          end
+        end
+        next
+      end
+
+      # Navegación entre pestañas con tecla Tab y Shift+Tab (\e[Z)
+      if @tabs && !@tabs.empty?
+        if key == "\t"
+          @active_tab_idx = (@active_tab_idx + 1) % @tabs.length
+          @functions = @tab_contents[@tabs[@active_tab_idx]] || []
+          @index = 0
+          @level = 0
+          @open_level = 0
+          @sub_index_1 = 0
+          @sub_index_2 = 0
+          @active_panel = :main
+          @submenu_open = false
+          draw_frame(target_width)
+          next
+        elsif key == "\e[Z"
+          @active_tab_idx = (@active_tab_idx - 1) % @tabs.length
+          @functions = @tab_contents[@tabs[@active_tab_idx]] || []
+          @index = 0
+          @level = 0
+          @open_level = 0
+          @sub_index_1 = 0
+          @sub_index_2 = 0
+          @active_panel = :main
+          @submenu_open = false
+          draw_frame(target_width)
+          next
+        end
+      end
+
+      # Control de teclado enfocado en submenú nivel 2
+      if @level == 2 && @open_level >= 2 && is_submenu_item?(@functions[@index])
+        s1_acts = get_submenu_actions(@functions[@index])
+        s2_acts = get_submenu_actions(s1_acts[@sub_index_1]) if s1_acts
+        if key == "\e[A" || key == "\eOA" || key == "\xe0H" || key == "\x00H"
+          @sub_index_2 = (@sub_index_2 - 1) % s2_acts.length if s2_acts && !s2_acts.empty?
+          draw_frame(target_width)
+          next
+        elsif key == "\e[B" || key == "\eOB" || key == "\xe0P" || key == "\x00P"
+          @sub_index_2 = (@sub_index_2 + 1) % s2_acts.length if s2_acts && !s2_acts.empty?
+          draw_frame(target_width)
+          next
+        elsif key == "\e[D" || key == "\eOD" || key == "\xe0K" || key == "\x00K" || key == "\e"
+          @open_level = 1
+          @level = 1
+          draw_frame(target_width)
+          next
+        elsif key == "\r" || key == "\n"
+          return s2_acts[@sub_index_2] if s2_acts && @sub_index_2 < s2_acts.length
+        end
+      end
+
+      # Control de teclado enfocado en submenú nivel 1
+      if @level == 1 && @open_level >= 1 && is_submenu_item?(@functions[@index])
+        s1_acts = get_submenu_actions(@functions[@index])
+        if key == "\e[A" || key == "\eOA" || key == "\xe0H" || key == "\x00H"
+          @sub_index_1 = (@sub_index_1 - 1) % s1_acts.length if s1_acts && !s1_acts.empty?
+          @sub_index_2 = 0
+          draw_frame(target_width)
+          next
+        elsif key == "\e[B" || key == "\eOB" || key == "\xe0P" || key == "\x00P"
+          @sub_index_1 = (@sub_index_1 + 1) % s1_acts.length if s1_acts && !s1_acts.empty?
+          @sub_index_2 = 0
+          draw_frame(target_width)
+          next
+        elsif key == "\e[D" || key == "\eOD" || key == "\xe0K" || key == "\x00K" || key == "\e"
+          @open_level = 0
+          @level = 0
+          @active_panel = :main
+          @submenu_open = false
+          draw_frame(target_width)
+          next
+        elsif key == "\e[C" || key == "\eOC" || key == "\xe0M" || key == "\x00M"
+          cur_l1 = s1_acts[@sub_index_1] if s1_acts
+          if is_submenu_item?(cur_l1)
+            @open_level = 2
+            @level = 2
+            @sub_index_2 = 0
+            draw_frame(target_width)
+            next
+          end
+        elsif key == "\r" || key == "\n"
+          cur_l1 = s1_acts[@sub_index_1] if s1_acts
+          if is_submenu_item?(cur_l1)
+            @open_level = 2
+            @level = 2
+            @sub_index_2 = 0
+            draw_frame(target_width)
+            next
+          else
+            return cur_l1
+          end
+        end
+      end
+
+      # Salir con 'q' si no estamos escribiendo en la barra de búsqueda
+      if !@search && (key == "q" || key == "Q")
+        break
+      end
+
+      # Tecla Escape: limpia búsqueda si hay texto, de lo contrario cierra el menú
+      if key == "\e"
+        if @search && !@query.empty?
+          @query.clear
+          matching = current_matching_indices
+          @index = matching.first || 0
+          draw_frame(target_width)
+        else
+          break
+        end
+      elsif key == "\e[A" || key == "\eOA" || key == "\xe0H" || key == "\x00H"
+        move_up
+        @sub_index_1 = 0
+        @sub_index_2 = 0
+        draw_frame(target_width)
+      elsif key == "\e[B" || key == "\eOB" || key == "\xe0P" || key == "\x00P"
+        move_down
+        @sub_index_1 = 0
+        @sub_index_2 = 0
+        draw_frame(target_width)
+      elsif key == "\e[D" || key == "\eOD" || key == "\xe0K" || key == "\x00K"
+        if @open_level > 0
+          @open_level = 0
+          @level = 0
+          @active_panel = :main
+          @submenu_open = false
+          draw_frame(target_width)
+        else
+          move_left
+          draw_frame(target_width)
+        end
+      elsif key == "\e[C" || key == "\eOC" || key == "\xe0M" || key == "\x00M"
+        if is_submenu_item?(@functions[@index])
+          @open_level = 1
+          @level = 1
+          @sub_index_1 = 0
+          @sub_index_2 = 0
+          @active_panel = :sub
+          @submenu_open = true
+          draw_frame(target_width)
+        else
+          move_right
+          draw_frame(target_width)
+        end
+      elsif key == "\x7f" || key == "\b" || key == "\x08"
+        # Backspace en el campo de búsqueda
+        if @search && !@query.empty?
+          @query.chop!
+          matching = current_matching_indices
+          @index = matching.first || 0
+          draw_frame(target_width)
+        end
+      elsif key == "\x15"
+        # Ctrl+U: limpiar búsqueda
+        if @search
+          @query.clear
+          matching = current_matching_indices
+          @index = matching.first || 0
+          draw_frame(target_width)
+        end
+      elsif key == "\r" || key == "\n"
+        # Enter: abrir submenú o ejecutar la opción actual
+        matching = current_matching_indices
+        if matching.include?(@index)
+          if is_submenu_item?(@functions[@index])
+            @open_level = 1
+            @level = 1
+            @sub_index_1 = 0
+            @sub_index_2 = 0
+            @active_panel = :sub
+            @submenu_open = true
+            draw_frame(target_width)
+          else
+            return @functions[@index]
+          end
+        end
+      elsif @search && key =~ /^[[:print:]]$/
+        # Agregar letra a la búsqueda y filtrar opciones
+        @query << key
+        matching = current_matching_indices
+        @index = matching.first || 0
+        draw_frame(target_width)
+      end
+    end
+
+    nil
+  end
+
+  # Lee una tecla individual o secuencia de escape desde el stream
+  def read_single_key(input_stream)
+    GRmenu.read_key_raw(input_stream)
+  end
+
+  # Transforma nombres en snake_case o kebab-case a palabras capitalizadas legibles
+  def format_auto_name(raw_name)
+    cleaned = raw_name.to_s.gsub(/[_-]+/, ' ').strip
+    cleaned.split(' ').map(&:capitalize).join(' ')
+  end
+
+  # Extrae la etiqueta visible para un elemento del menú según su tipo
+  def extract_name_from_action(action)
+    case action
+    when Array
+      action[0].to_s
+    when Hash
+      (action[:name] || action[:title] || action["name"] || action["title"] || "Opcion").to_s
+    when Method
+      format_auto_name(action.name)
+    when Symbol
+      format_auto_name(action)
+    when Proc
+      if action.respond_to?(:name) && action.name
+        format_auto_name(action.name)
+      else
+        "Opcion"
+      end
+    else
+      if action.respond_to?(:name)
+        format_auto_name(action.name)
+      elsif action.respond_to?(:title)
+        action.title.to_s
+      else
+        format_auto_name(action)
+      end
+    end
+  end
+
+  # Extrae la descripción secundaria asociada a una opción
+  def extract_description_from_action(action)
+    if action.is_a?(Array) && action.length >= 3
+      action[2].to_s
+    elsif action.is_a?(Hash)
+      (action[:desc] || action[:description] || action["desc"] || action["description"]).to_s
+    else
+      ""
+    end
+  end
+
+  # Ejecuta la acción seleccionada por el usuario (Proc, Method, Symbol o bloque invocable)
+  def execute_action(action)
+    case action
+    when Method, Proc
+      action.call
+    when Symbol
+      if Object.respond_to?(action, true)
+        Object.send(action)
+      elsif Kernel.respond_to?(action, true)
+        Kernel.send(action)
+      end
+    when Array
+      callable = action[1]
+      if callable.is_a?(Symbol)
+        if Object.respond_to?(callable, true)
+          Object.send(callable)
+        elsif Kernel.respond_to?(callable, true)
+          Kernel.send(callable)
+        end
+      elsif callable.respond_to?(:call)
+        callable.call
+      end
+    when Hash
+      callable = action[:action] || action[:call] || action["action"] || action["call"]
+      if callable.is_a?(Symbol)
+        if Object.respond_to?(callable, true)
+          Object.send(callable)
+        elsif Kernel.respond_to?(callable, true)
+          Kernel.send(callable)
+        end
+      elsif callable.respond_to?(:call)
+        callable.call
+      end
+    else
+      action.call if action.respond_to?(:call)
+    end
+  end
+end