zcatui/CLAUDE.md

zcatui - TUI Library para Zig

Última actualización: 2025-12-08 Versión: v2.0 - FEATURE COMPLETE Lenguaje: Zig 0.15.2 Inspiración: ratatui + crossterm (Rust) Estado: Librería completa y lista para producción

---

RESUMEN EJECUTIVO

zcatui es una librería TUI completa para Zig, equivalente a ratatui+crossterm de Rust pero en un solo paquete.

Estadísticas del Proyecto

Métrica	Valor
Archivos fuente	60 archivos .zig
Widgets	27 widgets
Módulos core	16 módulos
Tests	186+ tests
Examples	11 demos ejecutables
Líneas de código	~15,000+

Funcionalidades Principales

• ✅ Renderizado immediate-mode con double buffering y diff
• ✅ 27 widgets (más que ratatui)
• ✅ Sistema de eventos teclado/ratón
• ✅ Sistema de animaciones con easing
• ✅ Clipboard (OSC 52)
• ✅ Hyperlinks (OSC 8)
• ✅ Imágenes en terminal (Kitty/iTerm2)
• ✅ Notificaciones desktop (OSC 9/777)
• ✅ Focus management global
• ✅ Sistema de themes (10 themes predefinidos)
• ✅ Unicode width calculation (wcwidth)
• ✅ Terminal capability detection
• ✅ Lazy rendering con cache

---

ESTRUCTURA COMPLETA DEL PROYECTO

zcatui/
├── src/
│   ├── root.zig              # Entry point, re-exports públicos
│   │
│   ├── ─── CORE ───
│   ├── buffer.zig            # Buffer, Cell, Rect, Symbol, Margin
│   ├── style.zig             # Color, Style, Modifier
│   ├── text.zig              # Text, Line, Span, Alignment
│   ├── layout.zig            # Layout, Constraint, Direction
│   ├── terminal.zig          # Terminal abstraction
│   │
│   ├── ─── EVENTOS ───
│   ├── event.zig             # Event, KeyEvent, MouseEvent, KeyCode
│   ├── event/
│   │   ├── reader.zig        # EventReader con polling
│   │   └── parse.zig         # Parser de escape sequences
│   │
│   ├── ─── FEATURES ───
│   ├── focus.zig             # FocusRing, FocusManager, Focusable
│   ├── theme.zig             # Theme system (10 themes)
│   ├── animation.zig         # Animation, Easing, Timer, AnimationGroup
│   ├── cursor.zig            # Cursor control (shapes, position)
│   ├── clipboard.zig         # OSC 52 clipboard
│   ├── hyperlink.zig         # OSC 8 hyperlinks
│   ├── notification.zig      # OSC 9/777 notifications
│   ├── image.zig             # Kitty/iTerm2 images
│   ├── lazy.zig              # RenderCache, Throttle, Debounce
│   ├── unicode.zig           # charWidth, stringWidth (wcwidth)
│   ├── termcap.zig           # Terminal capability detection
│   │
│   ├── ─── BACKEND ───
│   ├── backend/
│   │   └── backend.zig       # ANSI escape sequences
│   │
│   ├── ─── SYMBOLS ───
│   ├── symbols/
│   │   ├── symbols.zig       # Re-exports
│   │   ├── line.zig          # Line drawing (─│┌┐└┘├┤┬┴┼)
│   │   ├── border.zig        # Border sets (single, double, rounded, thick)
│   │   ├── block.zig         # Block elements (█▀▄░▒▓)
│   │   ├── bar.zig           # Bar characters for charts
│   │   ├── braille.zig       # 256 braille patterns
│   │   ├── half_block.zig    # Half-block for pseudo-graphics
│   │   ├── scrollbar.zig     # Scrollbar symbols
│   │   └── marker.zig        # Chart markers (Dot, Braille, HalfBlock)
│   │
│   ├── ─── WIDGETS (27) ───
│   ├── widgets/
│   │   ├── block.zig         # Block (borders, titles, padding)
│   │   ├── paragraph.zig     # Text with wrapping
│   │   ├── list.zig          # Selectable list with state
│   │   ├── table.zig         # Multi-column table
│   │   ├── gauge.zig         # Gauge + LineGauge progress bars
│   │   ├── tabs.zig          # Tab navigation
│   │   ├── sparkline.zig     # Mini line graphs
│   │   ├── scrollbar.zig     # Scroll indicator
│   │   ├── barchart.zig      # Bar charts with groups
│   │   ├── canvas.zig        # Drawing (braille/half-block/block)
│   │   ├── chart.zig         # Line/scatter/bar graphs with axes
│   │   ├── calendar.zig      # Monthly calendar
│   │   ├── clear.zig         # Clear/reset area
│   │   ├── input.zig         # Readline-style text input
│   │   ├── textarea.zig      # Multi-line text editor
│   │   ├── popup.zig         # Popup + Modal dialogs
│   │   ├── menu.zig          # Menu, MenuBar, ContextMenu
│   │   ├── tooltip.zig       # Tooltip + TooltipManager
│   │   ├── tree.zig          # Tree view (expandable)
│   │   ├── filepicker.zig    # File/directory picker
│   │   ├── scroll.zig        # ScrollView, VirtualList, InfiniteScroll
│   │   ├── panel.zig         # Panel, PanelSplit, TabbedPanel, DockingPanel
│   │   ├── checkbox.zig      # Checkbox, RadioGroup, CheckboxGroup
│   │   ├── select.zig        # Select dropdown, MultiSelect
│   │   ├── slider.zig        # Slider, RangeSlider
│   │   └── statusbar.zig     # StatusBar, Toast, ToastManager
│   │
│   └── ─── TESTS ───
│   └── tests/
│       ├── tests.zig         # Test aggregator
│       ├── widget_tests.zig  # Widget tests
│       ├── theme_tests.zig   # Theme tests
│       └── layout_tests.zig  # Layout tests
│
├── examples/                  # 11 demos ejecutables
│   ├── hello.zig             # Minimal TUI app
│   ├── events_demo.zig       # Keyboard/mouse events
│   ├── list_demo.zig         # Lista navegable
│   ├── table_demo.zig        # Tabla con selección
│   ├── dashboard.zig         # Demo completo multi-widget
│   ├── input_demo.zig        # Input readline-style
│   ├── animation_demo.zig    # Easing functions showcase
│   ├── clipboard_demo.zig    # OSC 52 clipboard
│   ├── menu_demo.zig         # MenuBar + Modal
│   ├── form_demo.zig         # Form widgets
│   └── panel_demo.zig        # Panel system
│
├── docs/
│   ├── ARCHITECTURE.md       # Arquitectura técnica
│   ├── WIDGETS.md            # Guía de widgets
│   └── API.md                # Referencia rápida
│
├── build.zig
├── README.md                 # Documentación pública
└── CLAUDE.md                 # Este archivo

---

MÓDULOS DETALLADOS

Core

Módulo	Archivo	Descripción
Buffer	buffer.zig	Buffer de celdas, Cell, Rect, Symbol, diff rendering
Style	style.zig	Color (16/256/RGB), Style, Modifier
Text	text.zig	Text, Line, Span, StyledGrapheme, Alignment
Layout	layout.zig	Layout, Constraint (Length/Min/Max/Percentage/Ratio)
Terminal	terminal.zig	Terminal abstraction, raw mode

Eventos

Módulo	Archivo	Descripción
Event	event.zig	Event, KeyEvent, MouseEvent, KeyCode, KeyModifiers
EventReader	event/reader.zig	Polling de eventos con timeout
Parser	event/parse.zig	Parser de escape sequences (CSI, SS3, SGR mouse)

Features Avanzadas

Módulo	Archivo	Descripción
Focus	focus.zig	FocusRing, FocusManager, Focusable interface
Theme	theme.zig	10 themes: dark, light, dracula, nord, gruvbox, monokai...
Animation	animation.zig	Easing functions, Animation, Timer, AnimationGroup
Cursor	cursor.zig	Cursor shapes, visibility, save/restore
Clipboard	clipboard.zig	OSC 52 copy/paste
Hyperlink	hyperlink.zig	OSC 8 clickable links
Notification	notification.zig	OSC 9/777 desktop notifications
Image	image.zig	Kitty/iTerm2 inline images
Lazy	lazy.zig	RenderCache, Throttle, Debounce, DeferredRender
Unicode	unicode.zig	charWidth, stringWidth (wcwidth equivalent)
Termcap	termcap.zig	Terminal capability detection, color support

Widgets (27)

Widget	Archivo	Descripción
Block	block.zig	Contenedor con bordes y título
Paragraph	paragraph.zig	Texto con wrapping
List	list.zig	Lista seleccionable con estado
Table	table.zig	Tabla multi-columna
Gauge	gauge.zig	Barra de progreso
LineGauge	gauge.zig	Barra de progreso línea
Tabs	tabs.zig	Navegación por pestañas
Sparkline	sparkline.zig	Mini gráfico de línea
Scrollbar	scrollbar.zig	Indicador de scroll
BarChart	barchart.zig	Gráfico de barras
Canvas	canvas.zig	Dibujo libre (braille/block)
Chart	chart.zig	Gráficos con ejes
Calendar	calendar.zig	Calendario mensual
Clear	clear.zig	Limpiar área
Input	input.zig	Input readline-style
TextArea	textarea.zig	Editor multilínea
Popup	popup.zig	Overlay flotante
Modal	popup.zig	Diálogo con botones
Menu	menu.zig	Menú dropdown
MenuBar	menu.zig	Barra de menús
ContextMenu	menu.zig	Menú contextual
Tooltip	tooltip.zig	Información emergente
Tree	tree.zig	Árbol expandible
FilePicker	filepicker.zig	Selector de archivos
ScrollView	scroll.zig	Vista con scroll
VirtualList	scroll.zig	Lista virtual (large datasets)
Panel	panel.zig	Panel con foco
TabbedPanel	panel.zig	Panel con pestañas
Checkbox	checkbox.zig	Checkbox toggle
RadioGroup	checkbox.zig	Grupo de radio buttons
Select	select.zig	Dropdown select
Slider	slider.zig	Slider numérico
StatusBar	statusbar.zig	Barra de estado
Toast	statusbar.zig	Notificaciones toast

---

COMANDOS

# Ruta del compilador Zig
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig

# Compilar
zig build

# Tests (186+ tests)
zig build test

# Ejecutar ejemplos
zig build hello
zig build events-demo
zig build list-demo
zig build table-demo
zig build dashboard
zig build input-demo
zig build animation-demo
zig build clipboard-demo
zig build menu-demo
zig build form-demo
zig build panel-demo

---

THEMES DISPONIBLES

const Theme = zcatui.Theme;

// 10 themes predefinidos
const dark = zcatui.theme.dark;
const light = zcatui.theme.light;
const dracula = zcatui.theme.dracula;
const nord = zcatui.theme.nord;
const gruvbox = zcatui.theme.gruvbox;
const solarized_dark = zcatui.theme.solarized_dark;
const monokai = zcatui.theme.monokai;
const one_dark = zcatui.theme.one_dark;
const tokyo_night = zcatui.theme.tokyo_night;
const catppuccin = zcatui.theme.catppuccin;

// Uso
const style = theme.primaryStyle();
const error_style = theme.errorStyle();
const selection_style = theme.selectionStyle();

---

FOCUS MANAGEMENT

const FocusManager = zcatui.FocusManager;
const FocusRing = zcatui.FocusRing;

var manager = FocusManager{};

// Crear rings (grupos de widgets)
const main_ring = manager.createRing("main");
const modal_ring = manager.createRing("modal");

// Añadir widgets focusables
_ = main_ring.?.add(widget1.focusable());
_ = main_ring.?.add(widget2.focusable());

// Navegación
_ = manager.focusNext();     // Tab
_ = manager.focusPrev();     // Shift+Tab
_ = manager.focusFirst();    // Home
_ = manager.focusLast();     // End

// Focus trapping (para modales)
manager.setTrapFocus(true);

// Cambiar ring activo
_ = manager.setActiveRing("modal");

---

UNICODE WIDTH

const unicode = zcatui.unicode;

// Ancho de caracteres
unicode.charWidth('a');      // 1 (ASCII)
unicode.charWidth(0x4E2D);   // 2 (中 - CJK)
unicode.charWidth(0x0301);   // 0 (combining accent)

// Ancho de strings
unicode.stringWidth("Hello");      // 5
unicode.stringWidth("日本");        // 4 (2+2)
unicode.stringWidth("Hello日本");   // 9 (5+4)

// Truncar a ancho visual
const truncated = unicode.truncateToWidth("Hello World", 5);  // "Hello"

---

TERMINAL CAPABILITIES

const termcap = zcatui.termcap;

const caps = termcap.detect();

// Color support
if (caps.color_support.hasTrueColor()) {
    // RGB colors disponibles
} else if (caps.color_support.has256()) {
    // 256 colores
} else {
    // 8/16 colores básicos
}

// Features
caps.hyperlinks      // OSC 8 support
caps.images          // Kitty/Sixel
caps.clipboard       // OSC 52
caps.unicode         // UTF-8 support
caps.styled_underline // Curly underlines

// Adaptar colores al terminal
const adapted = termcap.adaptColor(caps, r, g, b);

---

STACK TÉCNICO

Componente	Elección
Lenguaje	Zig 0.15.2
Zig path	/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
Backend	ANSI escape sequences (portable)
Dependencias	Solo stdlib de Zig
Target	Linux primario, cross-platform compatible

---

EQUIPO Y METODOLOGÍA

Quiénes Somos

• Usuario (Arno): Desarrollador independiente, proyectos comerciales propios
• Claude: Asistente de programación (Claude Code / Opus 4.5)

Cómo Trabajamos

• Desarrollo iterativo con commits frecuentes
• Tests antes de features nuevas
• Documentación inline con /// doc comments
• Código idiomático Zig (snake_case, error handling explícito)
• Sin dependencias externas

Normas de Trabajo Centralizadas

IMPORTANTE: Todas las normas de trabajo están en:

/mnt/cello2/arno/re/recode/TEAM_STANDARDS/

Archivos clave a leer:

Archivo	Descripción
LAST_UPDATE.md	LEER PRIMERO - Cambios recientes
NORMAS_TRABAJO_CONSENSUADAS.md	Metodología fundamental
QUICK_REFERENCE.md	Cheat sheet rápido
INFRASTRUCTURE/	Documentación de servidores
PROJECTS/zcatui.md	Estado de este proyecto

Protocolo de Inicio de Conversación

1. Leer TEAM_STANDARDS/LAST_UPDATE.md (detectar cambios)
2. Leer este archivo CLAUDE.md
3. Verificar estado (git status, zig build test)
4. Continuar desde donde se dejó

---

CONTROL DE VERSIONES

# Remote
git@git.reugenio.com:reugenio/zcatui.git

# Estado actual
git log --oneline -5

---

OTROS PROYECTOS DEL ECOSISTEMA

Proyectos Zig

Proyecto	Descripción	Ubicación
zcatui	TUI library (este)	/mnt/cello2/arno/re/recode/zig/zcatui
service-monitor	Monitor HTTP/TCP	/mnt/cello2/arno/re/recode/zig/service-monitor

Proyectos Go (referencia)

Proyecto	Descripción
simifactu	API facturación electrónica
ms-web	E-commerce mundisofa
0fiS	Aplicación desktop Fyne

Infraestructura

Recurso	Ubicación
Git server	git.reugenio.com (Forgejo)
Servidor	Simba (188.245.244.244)
Docs infra	TEAM_STANDARDS/INFRASTRUCTURE/

---

RECURSOS Y REFERENCIAS

ratatui (Rust) - Referencia principal

• Repo: https://github.com/ratatui/ratatui
• Docs: https://docs.rs/ratatui/latest/ratatui/
• Website: https://ratatui.rs/

Zig

• Docs 0.15: https://ziglang.org/documentation/0.15.0/std/
• Guía migración: TEAM_STANDARDS/INFRASTRUCTURE/ZIG_0.15_GUIA.md

ANSI Escape Codes

• https://en.wikipedia.org/wiki/ANSI_escape_code
• https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797

---

HISTORIAL DE DESARROLLO

2025-12-08 - v2.0 (FEATURE COMPLETE)

Nuevos módulos:

• focus.zig - Focus management global (FocusRing, FocusManager)
• theme.zig - Sistema de themes (10 themes predefinidos)
• unicode.zig - Unicode width calculation (wcwidth)
• termcap.zig - Terminal capability detection

Tests:

• Suite de tests exhaustiva en src/tests/
• 186+ tests pasando
• Cobertura de widgets, layout, themes, focus

Correcciones Zig 0.15:

• style.fg → style.foreground
• std.time.sleep → std.Thread.sleep
• Cell.char → Cell.symbol
• Tipo i2 → i8 para charWidth

2025-12-08 - v1.4 (Form widgets + Panels)

Widgets nuevos:

• Checkbox, RadioGroup, CheckboxGroup
• Select, MultiSelect
• Slider, RangeSlider
• StatusBar, Toast, ToastManager
• Panel, PanelSplit, TabbedPanel, DockingPanel

Features:

• Tooltip + TooltipManager
• Tree widget
• FilePicker
• ScrollView, VirtualList, InfiniteScroll

2025-12-08 - v1.3 (Menus + Modals)

Widgets nuevos:

• Input (readline-style)
• Popup, Modal
• Menu, MenuBar, ContextMenu

Sistemas:

• Animation system (easing, timer, groups)
• Clipboard (OSC 52)
• Hyperlinks (OSC 8)
• Notifications (OSC 9/777)
• Images (Kitty/iTerm2)

2025-12-08 - v1.2 (Eventos)

• Sistema de eventos crossterm-style
• EventReader con polling
• Parser de escape sequences
• Cursor control

2025-12-08 - v1.1 (Performance)

• Symbol type compacto
• Buffer diff rendering
• Optimizaciones

2025-12-08 - v1.0 (Implementación inicial)

• 13 widgets base (ratatui equivalents)
• Sistema de símbolos
• 103+ tests iniciales

2025-12-08 - Inicio

• Creación del proyecto
• Definición de arquitectura

---

NOTAS PARA PRÓXIMAS CONVERSACIONES

Estado del Proyecto

• Librería COMPLETA - Todas las funcionalidades implementadas
• Tests pasando - 186+ tests
• Documentación completa - README.md, docs/, CLAUDE.md

Posibles Mejoras Futuras (opcionales)

• Performance: SIMD para operaciones de buffer
• Más examples específicos
• Tutorial paso a paso
• Publicación en package registry

Cosas a Recordar

• Zig 0.15.2 tiene cambios de API respecto a versiones anteriores
• El path del compilador está en /mnt/cello2/arno/re/recode/zig/zig-0.15.2/
• TEAM_STANDARDS contiene todas las normas de trabajo del equipo
• El usuario prefiere commits descriptivos con emoji 🤖
• Siempre verificar zig build test antes de commit

---

QUICK REFERENCE

# Build & Test
zig build
zig build test

# Run examples
zig build hello
zig build dashboard

# Git
git status
git add -A && git commit -m "mensaje"
git push

# Paths importantes
/mnt/cello2/arno/re/recode/zig/zcatui/           # Este proyecto
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/        # Normas trabajo
/mnt/cello2/arno/re/recode/zig/zig-0.15.2/...    # Compilador Zig