Biblioteca de componentes: Box/Input/Markdown/SelectList

源码版本v0.73.1

El directorio components/ de @mariozechner/pi-tui contiene componentes reutilizables, todos implementando la interfaz Component (render(width): string[] + invalidate()). Hay tres familias: layout (Box, Text, TruncatedText, Spacer), interactivos (Input, SelectList, SettingsList, Editor) y display (Markdown, Image, Loader). TUI no implementa componentes concretos, sólo agendar el árbol de componentes.

Responsabilidades

components/ hace tres cosas:

1. Interfaz unificada: todos los componentes implementan Component; render(width) devuelve un array de líneas con escapes ANSI, e invalidate() limpia la caché al cambiar el tema. Ver packages/tui/src/tui.ts:39-63.
2. Render cacheado: Text, Box, Markdown cachean cachedLines; si el texto y el ancho no cambiaron, devuelven el resultado anterior, evitando recalcular word-wrap en cada frame. Ver packages/tui/src/components/text.ts:45-58.
3. Protocolo Focusable: Input y Editor implementan Focusable (campo focused); TUI al hacer setFocus lo fija y el componente renderiza CURSOR_MARKER en la posición del cursor. Ver packages/tui/src/tui.ts:74-82.

Motivación de diseño

¿Por qué todos los componentes devuelven string[] en vez de escribir directamente? Porque TUI tiene que hacer diff: necesita cada línea final (con ANSI) para comparar con el frame anterior. El componente sólo genera líneas, no se preocupa de cómo se escriben a la terminal; así son testeables (función pura render(width) → string[]) y componibles (Container concatena las líneas de los children). Cuando Box pone color de fondo con bgFn, usa applyBackgroundToLine para intercalar el color entre los ANSI existentes en vez de envolver la línea, de modo que visibleWidth sigue calculando bien.

Archivos clave

Directorio packages/tui/src/components/:

• packages/tui/src/components/box.ts:14-60 — Contenedor Box, paddingX/Y + bgFn para color de fondo a un bloque, con caché de render.
• packages/tui/src/components/text.ts:7-58 — Text multilineal + word-wrap + función de fondo personalizada.
• packages/tui/src/components/truncated-text.ts:7-50 — TruncatedText toma sólo la primera línea y la corta por ancho, para la barra de estado.
• packages/tui/src/components/input.ts:18-50 — Input entrada de una línea, scroll horizontal, gestiona paste/kill-ring/undo (igual que Editor).
• packages/tui/src/components/select-list.ts:40-100 — SelectList lista de selección arriba/abajo, con filter, doble columna (principal + descripción) y scroll indicator.
• packages/tui/src/components/settings-list.ts:34-83 — SettingsList panel de configuración, con Input de búsqueda embebida + submenús recursivos.
• packages/tui/src/components/markdown.ts:78-159 — Markdown usa marked lexer + estilo inline custom para producir líneas con ANSI.
• packages/tui/src/components/loader.ts / packages/tui/src/components/cancellable-loader.ts — spinner, cada frame mueve sólo una línea, justo por la ruta rápida del diff.

Text.render si hay caché lo devuelve, si no recalcula word-wrap:

// packages/tui/src/components/text.ts:45-58
render(width: number): string[] {
  if (this.cachedLines && this.cachedText === this.text && this.cachedWidth === width) {
    return this.cachedLines;
  }
  if (!this.text || this.text.trim() === "") {
    const result: string[] = [];
    this.cachedText = this.text;
    this.cachedWidth = width;
    this.cachedLines = result;
    return result;
  }
  // Replace tabs with 3 spaces

SelectList.render usa startIndex para desplazar la ventana y dibuja sólo maxVisible elementos; el seleccionado se destaca con prefijo:

// packages/tui/src/components/select-list.ts:74-100
render(width: number): string[] {
  const lines: string[] = [];
  if (this.filteredItems.length === 0) {
    lines.push(this.theme.noMatch("  No matching commands"));
    return lines;
  }
  const primaryColumnWidth = this.getPrimaryColumnWidth();
  const startIndex = Math.max(
    0,
    Math.min(this.selectedIndex - Math.floor(this.maxVisible / 2), this.filteredItems.length - this.maxVisible),
  );
  const endIndex = Math.min(startIndex + this.maxVisible, this.filteredItems.length);

Markdown.render primero lexica con marked, convierte cada token a líneas con estilo, luego wrapTextWithAnsi reenvuelve por ancho de columna y al final padding/background:

// packages/tui/src/components/markdown.ts:116-159
render(width: number): string[] {
  if (this.cachedLines && this.cachedText === this.text && this.cachedWidth === width) {
    return this.cachedLines;
  }
  const contentWidth = Math.max(1, width - this.paddingX * 2);
  // ...
  const tokens = markdownParser.lexer(normalizedText);
  const renderedLines: string[] = [];
  for (let i = 0; i < tokens.length; i++) {
    const token = tokens[i];
    const tokenLines = this.renderToken(token, contentWidth, nextToken?.type);
    renderedLines.push(...tokenLines);
  }

Flujo de datos

Cómo la salida de render de los componentes entra al diff de TUI:

Límites y fallos

• Invalidación por invalidate: al cambiar el tema, TUI llama Container.invalidate que limpia recursivamente la caché de los children. Las subclases deben sobrescribir invalidate para limpiar su propio cachedLines, si no usarán líneas con el tema viejo. Ver packages/tui/src/components/markdown.ts:110-114.
• visibleWidth debe calcular bien: Box con padding puede superar width y TUI crashea al detectarlo. Box.matchCache usa bgSample para detectar cambios en la salida de bgFn y decidir si la caché aplica. Ver packages/tui/src/components/box.ts:56-65.
• SelectList lista vacía fallback: si filteredItems.length === 0 dibuja theme.noMatch("No matching commands"), sin lanzar, para que el llamador siga corriendo.
• Markdown no envuelve líneas de imagen: las líneas con isImageLine(line) se empujan sin pasar por wrapTextWithAnsi, porque romper las secuencias kitty graphics las corrompería.
• Input una sola línea sin word-wrap: Input es una versión simplificada de Editor; el comportamiento ante un pegado con \n depende de handlePaste. Input se usa sobre todo en la caja de búsqueda de SelectList y en los submenús de SettingsList, no sirve para editar multilínea.

Resumen

components/ es el conjunto de implementaciones de la interfaz Component: los de layout (Box/Text) para composición, los interactivos (Input/SelectList/Editor) para entrada, los de display (Markdown/Loader) para render. Todos se apoyan en el bucle diff de la clase TUI para escribir cambios; Editor es el más complejo, ver componente editor; el parseo del byte stream de teclado a handleInput en parseo de teclado: protocolo kitty.