@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/tui/lib/render.js

@@ -1,264 +1,264 @@
-'use strict';
-
-/**
- * Primitivas de render para la TUI custom de swl-ses.
- * Zero-deps. Solo escape codes ANSI estándar + readline para keypress.
- *
- * Modelo:
- *   - `iniciarModoTui()` entra al alternate screen buffer, oculta cursor.
- *   - `salirModoTui()` restaura el buffer principal y muestra el cursor.
- *   - Cada pantalla llama `limpiarPantalla()` y dibuja desde (1,1).
- *   - Las coordenadas son 1-based (compatibilidad con escape codes ANSI).
- *
- * Diseño defensivo:
- *   - Si stdout no es TTY (CI, pipe), todas las funciones de cursor son no-op
- *     y los dibujos se reducen a console.log lineal.
- *   - Capturar SIGINT y exit para garantizar salirModoTui() siempre.
- */
-
-const { colores, borde, iconos } = require('./colores');
-
-const ES_TTY = !!process.stdout.isTTY;
-
-// ---------------------------------------------------------------------------
-// Control del terminal
-// ---------------------------------------------------------------------------
-
-let modoTuiActivo = false;
-let limpiezaRegistrada = false;
-
-function iniciarModoTui() {
-  if (modoTuiActivo || !ES_TTY) return;
-  modoTuiActivo = true;
-
-  // Alternate screen buffer: preserva el contenido del terminal pre-TUI
-  process.stdout.write('\x1b[?1049h');
-  // Ocultar cursor
-  process.stdout.write('\x1b[?25l');
-  // Limpiar
-  process.stdout.write('\x1b[2J\x1b[H');
-
-  // Registrar limpieza al salir (idempotente)
-  if (!limpiezaRegistrada) {
-    limpiezaRegistrada = true;
-    const limpieza = () => salirModoTui();
-    process.once('exit', limpieza);
-    process.once('SIGINT', () => { salirModoTui(); process.exit(130); });
-    process.once('SIGTERM', () => { salirModoTui(); process.exit(143); });
-  }
-}
-
-function salirModoTui() {
-  if (!modoTuiActivo || !ES_TTY) return;
-  modoTuiActivo = false;
-
-  // Mostrar cursor
-  process.stdout.write('\x1b[?25h');
-  // Salir del alternate screen buffer (restaura contenido pre-TUI)
-  process.stdout.write('\x1b[?1049l');
-}
-
-function estaActivo() {
-  return modoTuiActivo;
-}
-
-// ---------------------------------------------------------------------------
-// Movimiento de cursor
-// ---------------------------------------------------------------------------
-
-function moverCursor(fila, col) {
-  if (!ES_TTY) return;
-  process.stdout.write(`\x1b[${fila};${col}H`);
-}
-
-function limpiarPantalla() {
-  if (!ES_TTY) return;
-  process.stdout.write('\x1b[2J\x1b[H');
-}
-
-function limpiarLinea() {
-  if (!ES_TTY) return;
-  process.stdout.write('\x1b[2K\r');
-}
-
-function obtenerDimensiones() {
-  return {
-    cols: process.stdout.columns || 80,
-    rows: process.stdout.rows || 24,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Escritura posicionada
-// ---------------------------------------------------------------------------
-
-/**
- * Escribe texto en una posición específica de la pantalla. El texto
- * puede contener escape codes ANSI (colores) — no se cuentan en la longitud.
- */
-function escribirEn(fila, col, texto) {
-  moverCursor(fila, col);
-  process.stdout.write(texto);
-}
-
-/**
- * Cuenta la longitud visual de un string ignorando códigos ANSI.
- * Útil para centrar/alinear texto con color sin distorsionar el cálculo.
- */
-function anchoVisual(texto) {
-  return String(texto).replace(/\x1b\[[0-9;]*m/g, '').length;
-}
-
-/**
- * Recorta un string a `maxAncho` caracteres visuales preservando códigos ANSI.
- * Si excede, agrega '…' al final.
- */
-function recortar(texto, maxAncho) {
-  const s = String(texto);
-  if (anchoVisual(s) <= maxAncho) return s;
-
-  // Conservar códigos ANSI mientras se cuentan solo caracteres visibles
-  let resultado = '';
-  let ancho = 0;
-  let i = 0;
-  while (i < s.length && ancho < maxAncho - 1) {
-    if (s[i] === '\x1b' && s[i + 1] === '[') {
-      // copiar el escape code completo sin contar
-      const finCode = s.indexOf('m', i);
-      if (finCode === -1) break;
-      resultado += s.slice(i, finCode + 1);
-      i = finCode + 1;
-    } else {
-      resultado += s[i];
-      ancho++;
-      i++;
-    }
-  }
-  return resultado + '…\x1b[0m';
-}
-
-/**
- * Rellena un string a `ancho` caracteres visuales con espacios a la derecha.
- */
-function rellenarDer(texto, ancho) {
-  const diff = ancho - anchoVisual(texto);
-  return diff > 0 ? String(texto) + ' '.repeat(diff) : recortar(texto, ancho);
-}
-
-/**
- * Centra un string en `ancho` caracteres visuales.
- */
-function centrar(texto, ancho) {
-  const sobra = ancho - anchoVisual(texto);
-  if (sobra <= 0) return recortar(texto, ancho);
-  const izq = Math.floor(sobra / 2);
-  const der = sobra - izq;
-  return ' '.repeat(izq) + texto + ' '.repeat(der);
-}
-
-// ---------------------------------------------------------------------------
-// Cajas y paneles
-// ---------------------------------------------------------------------------
-
-/**
- * Dibuja una caja con borde rounded en (fila, col) con ancho y alto dados.
- * Opciones:
- *   - titulo: string opcional centrado en la línea superior
- *   - color: función de color a aplicar al borde
- *   - doble: usar borde doble (═║) en lugar de rounded (─│)
- *   - resaltado: invertir colores del borde (para indicar foco)
- */
-function dibujarCaja(fila, col, ancho, alto, opts = {}) {
-  if (!ES_TTY) return;
-  if (ancho < 2 || alto < 2) return;
-
-  const c = opts.color || colores.gris;
-  const b = opts.doble ? {
-    esqSI: borde.dbEsqSupIzq, esqSD: borde.dbEsqSupDer,
-    esqII: borde.dbEsqInfIzq, esqID: borde.dbEsqInfDer,
-    h: borde.dbHorizontal,    v: borde.dbVertical,
-  } : {
-    esqSI: borde.esquinaSupIzq, esqSD: borde.esquinaSupDer,
-    esqII: borde.esquinaInfIzq, esqID: borde.esquinaInfDer,
-    h: borde.horizontal,        v: borde.vertical,
-  };
-
-  // Línea superior con título opcional
-  let lineaSup;
-  if (opts.titulo) {
-    const tituloRecortado = recortar(opts.titulo, ancho - 4);
-    const anchoTitulo = anchoVisual(tituloRecortado);
-    const izq = b.h.repeat(2);
-    const der = b.h.repeat(Math.max(0, ancho - 4 - anchoTitulo));
-    lineaSup = c(b.esqSI + izq) + ' ' + tituloRecortado + ' ' + c(der + b.esqSD);
-  } else {
-    lineaSup = c(b.esqSI + b.h.repeat(ancho - 2) + b.esqSD);
-  }
-  escribirEn(fila, col, lineaSup);
-
-  // Laterales
-  for (let f = fila + 1; f < fila + alto - 1; f++) {
-    escribirEn(f, col, c(b.v));
-    escribirEn(f, col + ancho - 1, c(b.v));
-  }
-
-  // Línea inferior
-  escribirEn(fila + alto - 1, col, c(b.esqII + b.h.repeat(ancho - 2) + b.esqID));
-}
-
-/**
- * Dibuja una barra horizontal de progreso en (fila, col) con ancho dado.
- * Porcentaje entre 0 y 1. Estilo: [████░░░░░░] 42%
- */
-function dibujarBarra(fila, col, ancho, porcentaje, opts = {}) {
-  const pct = Math.max(0, Math.min(1, porcentaje));
-  const lleno = opts.charLleno || '█';
-  const vacio = opts.charVacio || '░';
-  const colorLleno = opts.colorLleno || colores.verde;
-  const colorVacio = opts.colorVacio || colores.dim;
-
-  const anchoBarra = ancho - 7; // reservar espacio para " 100%"
-  const llenoN = Math.round(pct * anchoBarra);
-  const vacioN = anchoBarra - llenoN;
-
-  const barra = colorLleno(lleno.repeat(llenoN)) + colorVacio(vacio.repeat(vacioN));
-  const pctStr = String(Math.round(pct * 100)).padStart(3) + '%';
-
-  escribirEn(fila, col, barra + ' ' + colores.dim(pctStr));
-}
-
-/**
- * Dibuja una línea de pie (footer hint) con atajos de teclado.
- * Ejemplo: "↑↓ navegar · Enter elegir · Esc salir"
- */
-function dibujarPiePagina(atajos) {
-  const { rows, cols } = obtenerDimensiones();
-  const sep = colores.dim(' · ');
-  const linea = atajos
-    .map(([tecla, accion]) => `${colores.cyan(tecla)} ${colores.dim(accion)}`)
-    .join(sep);
-  escribirEn(rows, 1, ' ' + recortar(linea, cols - 2));
-}
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  ES_TTY,
-  iniciarModoTui,
-  salirModoTui,
-  estaActivo,
-  moverCursor,
-  limpiarPantalla,
-  limpiarLinea,
-  obtenerDimensiones,
-  escribirEn,
-  anchoVisual,
-  recortar,
-  rellenarDer,
-  centrar,
-  dibujarCaja,
-  dibujarBarra,
-  dibujarPiePagina,
-};
+'use strict';
+
+/**
+ * Primitivas de render para la TUI custom de swl-ses.
+ * Zero-deps. Solo escape codes ANSI estándar + readline para keypress.
+ *
+ * Modelo:
+ *   - `iniciarModoTui()` entra al alternate screen buffer, oculta cursor.
+ *   - `salirModoTui()` restaura el buffer principal y muestra el cursor.
+ *   - Cada pantalla llama `limpiarPantalla()` y dibuja desde (1,1).
+ *   - Las coordenadas son 1-based (compatibilidad con escape codes ANSI).
+ *
+ * Diseño defensivo:
+ *   - Si stdout no es TTY (CI, pipe), todas las funciones de cursor son no-op
+ *     y los dibujos se reducen a console.log lineal.
+ *   - Capturar SIGINT y exit para garantizar salirModoTui() siempre.
+ */
+
+const { colores, borde, iconos } = require('./colores');
+
+const ES_TTY = !!process.stdout.isTTY;
+
+// ---------------------------------------------------------------------------
+// Control del terminal
+// ---------------------------------------------------------------------------
+
+let modoTuiActivo = false;
+let limpiezaRegistrada = false;
+
+function iniciarModoTui() {
+  if (modoTuiActivo || !ES_TTY) return;
+  modoTuiActivo = true;
+
+  // Alternate screen buffer: preserva el contenido del terminal pre-TUI
+  process.stdout.write('\x1b[?1049h');
+  // Ocultar cursor
+  process.stdout.write('\x1b[?25l');
+  // Limpiar
+  process.stdout.write('\x1b[2J\x1b[H');
+
+  // Registrar limpieza al salir (idempotente)
+  if (!limpiezaRegistrada) {
+    limpiezaRegistrada = true;
+    const limpieza = () => salirModoTui();
+    process.once('exit', limpieza);
+    process.once('SIGINT', () => { salirModoTui(); process.exit(130); });
+    process.once('SIGTERM', () => { salirModoTui(); process.exit(143); });
+  }
+}
+
+function salirModoTui() {
+  if (!modoTuiActivo || !ES_TTY) return;
+  modoTuiActivo = false;
+
+  // Mostrar cursor
+  process.stdout.write('\x1b[?25h');
+  // Salir del alternate screen buffer (restaura contenido pre-TUI)
+  process.stdout.write('\x1b[?1049l');
+}
+
+function estaActivo() {
+  return modoTuiActivo;
+}
+
+// ---------------------------------------------------------------------------
+// Movimiento de cursor
+// ---------------------------------------------------------------------------
+
+function moverCursor(fila, col) {
+  if (!ES_TTY) return;
+  process.stdout.write(`\x1b[${fila};${col}H`);
+}
+
+function limpiarPantalla() {
+  if (!ES_TTY) return;
+  process.stdout.write('\x1b[2J\x1b[H');
+}
+
+function limpiarLinea() {
+  if (!ES_TTY) return;
+  process.stdout.write('\x1b[2K\r');
+}
+
+function obtenerDimensiones() {
+  return {
+    cols: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Escritura posicionada
+// ---------------------------------------------------------------------------
+
+/**
+ * Escribe texto en una posición específica de la pantalla. El texto
+ * puede contener escape codes ANSI (colores) — no se cuentan en la longitud.
+ */
+function escribirEn(fila, col, texto) {
+  moverCursor(fila, col);
+  process.stdout.write(texto);
+}
+
+/**
+ * Cuenta la longitud visual de un string ignorando códigos ANSI.
+ * Útil para centrar/alinear texto con color sin distorsionar el cálculo.
+ */
+function anchoVisual(texto) {
+  return String(texto).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+/**
+ * Recorta un string a `maxAncho` caracteres visuales preservando códigos ANSI.
+ * Si excede, agrega '…' al final.
+ */
+function recortar(texto, maxAncho) {
+  const s = String(texto);
+  if (anchoVisual(s) <= maxAncho) return s;
+
+  // Conservar códigos ANSI mientras se cuentan solo caracteres visibles
+  let resultado = '';
+  let ancho = 0;
+  let i = 0;
+  while (i < s.length && ancho < maxAncho - 1) {
+    if (s[i] === '\x1b' && s[i + 1] === '[') {
+      // copiar el escape code completo sin contar
+      const finCode = s.indexOf('m', i);
+      if (finCode === -1) break;
+      resultado += s.slice(i, finCode + 1);
+      i = finCode + 1;
+    } else {
+      resultado += s[i];
+      ancho++;
+      i++;
+    }
+  }
+  return resultado + '…\x1b[0m';
+}
+
+/**
+ * Rellena un string a `ancho` caracteres visuales con espacios a la derecha.
+ */
+function rellenarDer(texto, ancho) {
+  const diff = ancho - anchoVisual(texto);
+  return diff > 0 ? String(texto) + ' '.repeat(diff) : recortar(texto, ancho);
+}
+
+/**
+ * Centra un string en `ancho` caracteres visuales.
+ */
+function centrar(texto, ancho) {
+  const sobra = ancho - anchoVisual(texto);
+  if (sobra <= 0) return recortar(texto, ancho);
+  const izq = Math.floor(sobra / 2);
+  const der = sobra - izq;
+  return ' '.repeat(izq) + texto + ' '.repeat(der);
+}
+
+// ---------------------------------------------------------------------------
+// Cajas y paneles
+// ---------------------------------------------------------------------------
+
+/**
+ * Dibuja una caja con borde rounded en (fila, col) con ancho y alto dados.
+ * Opciones:
+ *   - titulo: string opcional centrado en la línea superior
+ *   - color: función de color a aplicar al borde
+ *   - doble: usar borde doble (═║) en lugar de rounded (─│)
+ *   - resaltado: invertir colores del borde (para indicar foco)
+ */
+function dibujarCaja(fila, col, ancho, alto, opts = {}) {
+  if (!ES_TTY) return;
+  if (ancho < 2 || alto < 2) return;
+
+  const c = opts.color || colores.gris;
+  const b = opts.doble ? {
+    esqSI: borde.dbEsqSupIzq, esqSD: borde.dbEsqSupDer,
+    esqII: borde.dbEsqInfIzq, esqID: borde.dbEsqInfDer,
+    h: borde.dbHorizontal,    v: borde.dbVertical,
+  } : {
+    esqSI: borde.esquinaSupIzq, esqSD: borde.esquinaSupDer,
+    esqII: borde.esquinaInfIzq, esqID: borde.esquinaInfDer,
+    h: borde.horizontal,        v: borde.vertical,
+  };
+
+  // Línea superior con título opcional
+  let lineaSup;
+  if (opts.titulo) {
+    const tituloRecortado = recortar(opts.titulo, ancho - 4);
+    const anchoTitulo = anchoVisual(tituloRecortado);
+    const izq = b.h.repeat(2);
+    const der = b.h.repeat(Math.max(0, ancho - 4 - anchoTitulo));
+    lineaSup = c(b.esqSI + izq) + ' ' + tituloRecortado + ' ' + c(der + b.esqSD);
+  } else {
+    lineaSup = c(b.esqSI + b.h.repeat(ancho - 2) + b.esqSD);
+  }
+  escribirEn(fila, col, lineaSup);
+
+  // Laterales
+  for (let f = fila + 1; f < fila + alto - 1; f++) {
+    escribirEn(f, col, c(b.v));
+    escribirEn(f, col + ancho - 1, c(b.v));
+  }
+
+  // Línea inferior
+  escribirEn(fila + alto - 1, col, c(b.esqII + b.h.repeat(ancho - 2) + b.esqID));
+}
+
+/**
+ * Dibuja una barra horizontal de progreso en (fila, col) con ancho dado.
+ * Porcentaje entre 0 y 1. Estilo: [████░░░░░░] 42%
+ */
+function dibujarBarra(fila, col, ancho, porcentaje, opts = {}) {
+  const pct = Math.max(0, Math.min(1, porcentaje));
+  const lleno = opts.charLleno || '█';
+  const vacio = opts.charVacio || '░';
+  const colorLleno = opts.colorLleno || colores.verde;
+  const colorVacio = opts.colorVacio || colores.dim;
+
+  const anchoBarra = ancho - 7; // reservar espacio para " 100%"
+  const llenoN = Math.round(pct * anchoBarra);
+  const vacioN = anchoBarra - llenoN;
+
+  const barra = colorLleno(lleno.repeat(llenoN)) + colorVacio(vacio.repeat(vacioN));
+  const pctStr = String(Math.round(pct * 100)).padStart(3) + '%';
+
+  escribirEn(fila, col, barra + ' ' + colores.dim(pctStr));
+}
+
+/**
+ * Dibuja una línea de pie (footer hint) con atajos de teclado.
+ * Ejemplo: "↑↓ navegar · Enter elegir · Esc salir"
+ */
+function dibujarPiePagina(atajos) {
+  const { rows, cols } = obtenerDimensiones();
+  const sep = colores.dim(' · ');
+  const linea = atajos
+    .map(([tecla, accion]) => `${colores.cyan(tecla)} ${colores.dim(accion)}`)
+    .join(sep);
+  escribirEn(rows, 1, ' ' + recortar(linea, cols - 2));
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  ES_TTY,
+  iniciarModoTui,
+  salirModoTui,
+  estaActivo,
+  moverCursor,
+  limpiarPantalla,
+  limpiarLinea,
+  obtenerDimensiones,
+  escribirEn,
+  anchoVisual,
+  recortar,
+  rellenarDer,
+  centrar,
+  dibujarCaja,
+  dibujarBarra,
+  dibujarPiePagina,
+};