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](https://github.com/ratatui/ratatui) + [crossterm](https://github.com/crossterm-rs/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

```bash
# 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

```zig
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

```zig
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

```zig
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

```zig
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

```bash
# 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

```bash
# 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
```