Un popup usable: cerrar, limpiar y no estorbar

Abrir una ventana flotante cuesta ocho líneas. Cerrarla bien cuesta el resto de la lección. La diferencia entre una demostración y un componente que puedes poner en tu configuración durante un año está enteramente en el ciclo de vida: qué pasa cuando el usuario pulsa q, qué pasa cuando se va a otra ventana sin cerrarla, qué pasa cuando redimensiona el terminal con el panel abierto, qué pasa cuando abre el mismo panel dos veces seguidas. Cada una de esas preguntas tiene una respuesta correcta y varias que producen buffers huérfanos, ventanas invisibles que retienen memoria o errores rojos al invocar una función sobre una ventana que ya no existe. Esta lección construye un popup completo y defiende cada decisión.

Cerrar es una decisión del buffer, no del editor

La forma incorrecta de hacer que q cierre el panel es una asignación global. La correcta es una asignación local al buffer, que existe solo mientras existe ese buffer y desaparece con él. Como el buffer es efímero y no lo comparte nadie, no hay riesgo de pisar la tecla de grabación de macros en ningún otro sitio.

local function cerrar(win, buf)
  if win and vim.api.nvim_win_is_valid(win) then
    vim.api.nvim_win_close(win, true)          -- force = true: cierra aunque este modificado
  end
  if buf and vim.api.nvim_buf_is_valid(buf) then
    vim.api.nvim_buf_delete(buf, { force = true })
  end
end

local function asignar_cierres(win, buf)
  local opts = { buffer = buf, nowait = true, silent = true, desc = "cerrar el panel" }
  for _, tecla in ipairs({ "q", "<Esc>" }) do
    vim.keymap.set("n", tecla, function() cerrar(win, buf) end, opts)
  end
end

Tres detalles de esas opciones merecen justificación. nowait evita que Neovim se quede esperando por si el usuario está tecleando una secuencia más larga que empiece por q, lo que produce una demora perceptible. silent impide que la asignación se haga eco en la línea de comandos. Y el orden de la comprobación en cerrar importa: cerrar la ventana antes de borrar el buffer evita que Neovim tenga que decidir qué mostrar en una ventana cuyo buffer acaba de desaparecer.

Merece la pena hacer el buffer inmune a la edición accidental. Poner modifiable a falso y readonly a verdadero tras escribir el contenido evita el caso, muy real, del usuario que pulsa una tecla cualquiera esperando que cierre y en su lugar inserta un carácter en un panel que se suponía informativo.

Perder el foco es la señal más honesta

Una flotante que sigue ahí cuando ya estás escribiendo en otra ventana es basura visual. El editor emite dos eventos útiles para detectarlo, y elegir mal entre ellos produce fallos difíciles de diagnosticar.

WinLeave se dispara al abandonar una ventana, incluida la tuya, pero también en travesías intermedias que no significan que el usuario haya terminado. BufLeave es análogo para buffers. El evento robusto es WinClosed para reaccionar al cierre, y para el foco la práctica sólida es escuchar WinEnter y comprobar si la ventana que acaba de recibir el foco es la nuestra.

local function cerrar_al_perder_foco(win, buf)
  local grupo = vim.api.nvim_create_augroup("panel_foco_" .. buf, { clear = true })

  vim.api.nvim_create_autocmd({ "WinEnter", "BufEnter" }, {
    group = grupo,
    callback = function()
      if vim.api.nvim_get_current_win() ~= win then cerrar(win, buf) end
    end,
  })

  -- Si la ventana muere por otra via, el grupo debe irse con ella
  vim.api.nvim_create_autocmd("WinClosed", {
    group = grupo,
    pattern = tostring(win),
    callback = function() pcall(vim.api.nvim_del_augroup_by_id, grupo) end,
  })
end

El patrón que sostiene todo esto es el grupo de autocomandos con nombre único por instancia. Sin él, abrir el panel dos veces registra dos manejadores y el segundo actúa sobre una ventana ya cerrada. Con clear a verdadero, la segunda apertura borra los manejadores de la primera antes de registrar los suyos, lo que hace que la operación sea idempotente por construcción.

El segundo autocomando es igual de importante y suele faltar. Los manejadores registrados globalmente sobreviven a la ventana que los motivó, y un editor que acumula grupos de autocomandos muertos ejecuta trabajo inútil en cada movimiento del cursor. Escuchar WinClosed filtrado por el identificador de la ventana y desmontar el grupo es lo que cierra el círculo.

flowchart TB
a[Abrir panel] --> b[Buffer scratch mas ventana flotante]
b --> c[Asignaciones locales al buffer]
b --> d[Grupo de autocomandos unico por instancia]
c --> e{Motivo del cierre}
d --> e
e -->|tecla q o Escape| f[cerrar]
e -->|WinEnter en otra ventana| f
e -->|WinClosed externo| f
f --> g[Cerrar ventana si es valida]
g --> h[Borrar buffer si es valido]
h --> i[Eliminar el grupo de autocomandos]
style b fill:#89b4fa,color:#11111b
style i fill:#a6e3a1,color:#11111b

No dejar nada colgando

El fallo silencioso más común de los paneles caseros es la fuga de buffers. Se produce porque hay más rutas de cierre de las que uno imagina: la tecla asignada, el evento de foco, un :q escrito a mano, el cierre de la pestaña entera, :qa durante la salida del editor, o un error de Lua a mitad de la construcción que deja el buffer creado y la ventana no.

La defensa es una función de limpieza idempotente —invocarla dos veces no debe fallar— y llamarla desde todas las rutas. Las comprobaciones de validez que aparecen en cerrar no son paranoia: nvim_win_close sobre una ventana ya cerrada lanza un error, y ese error, si ocurre dentro de un autocomando, produce un mensaje rojo que el usuario asocia a tu plugin sin saber por qué.

-- Escribir contenido y blindar el buffer contra edicion accidental
local function llenar(buf, lineas)
  vim.bo[buf].modifiable = true
  vim.api.nvim_buf_set_lines(buf, 0, -1, false, lineas)
  vim.bo[buf].modifiable = false
  vim.bo[buf].readonly = true
  vim.bo[buf].bufhidden = "wipe"     -- red de seguridad: sin ventana, el buffer se borra
end

Poner bufhidden a wipe es la red de seguridad definitiva: si por cualquier motivo la ventana desaparece sin pasar por tu función de limpieza, el buffer se elimina solo al quedarse sin vista. No sustituye a la limpieza explícita, pero convierte una fuga en un no evento.

Respetar el terminal

Un panel de 100 columnas de ancho es razonable en una pantalla amplia y un desastre en un terminal de 80. Las dimensiones no deben ser constantes, sino funciones del espacio disponible, con un mínimo por debajo del cual el panel simplemente no se abre.

local function geometria(prop_ancho, prop_alto)
  local ancho = math.max(20, math.min(math.floor(vim.o.columns * prop_ancho), vim.o.columns - 4))
  local alto  = math.max(3,  math.min(math.floor(vim.o.lines   * prop_alto),  vim.o.lines - 6))
  return {
    relative = "editor", width = ancho, height = alto,
    row = math.floor((vim.o.lines - alto) / 2) - 1,
    col = math.floor((vim.o.columns - ancho) / 2),
  }
end

vim.api.nvim_create_autocmd("VimResized", {
  group = grupo,
  callback = function()
    if vim.api.nvim_win_is_valid(win) then
      vim.api.nvim_win_set_config(win, geometria(0.8, 0.8))
    end
  end,
})

El descuento de filas no es arbitrario: la línea de comandos, la línea de estado global y el borde de la flotante consumen espacio que no puedes usar. Calcular la posición vertical sin restarlos produce un panel cuyo borde inferior queda tapado por la línea de comandos, síntoma inconfundible de una interfaz escrita sin medir.