zcatgui/CLAUDE.md

# zcatgui - GUI Library para Zig

> **IMPORTANTE PARA CLAUDE**: Lee la sección "PROTOCOLO DE INICIO" antes de hacer cualquier cosa.

---

## PROTOCOLO DE INICIO (LEER PRIMERO)

### Paso 1: Leer normas del equipo
```
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/LAST_UPDATE.md
```

### Paso 2: Leer normas completas si es necesario
```
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/NORMAS_TRABAJO_CONSENSUADAS.md
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/QUICK_REFERENCE.md
```

### Paso 3: Leer documentación de investigación
```
docs/DEVELOPMENT_PLAN.md                   # ⭐ PLAN MAESTRO - Leer primero
docs/research/WIDGET_COMPARISON.md         # Comparativa zcatgui vs DVUI vs Gio
docs/research/GIO_UI_ANALYSIS.md          # Análisis de Gio UI (Go)
docs/research/IMMEDIATE_MODE_LIBS.md      # Comparativa librerías immediate-mode
docs/research/SIMIFACTU_FYNE_ANALYSIS.md  # Requisitos extraídos de Simifactu
docs/ARCHITECTURE.md                       # Arquitectura y decisiones de diseño
```

### Paso 4: Verificar estado del proyecto
```bash
cd /mnt/cello2/arno/re/recode/zig/zcatgui
git status
git log --oneline -3
zig build test
```

### Paso 5: Continuar trabajo
Una vez verificado el estado, continúa desde donde se dejó.

---

## INFORMACIÓN DEL PROYECTO

| Campo | Valor |
|-------|-------|
| **Nombre** | zcatgui |
| **Versión** | v0.5.0 |
| **Fecha inicio** | 2025-12-09 |
| **Target** | v1.0.0 (35 widgets, paridad DVUI) |
| **Lenguaje** | Zig 0.15.2 |
| **Paradigma** | Immediate Mode GUI |
| **Inspiración** | Gio (Go), microui (C), DVUI (Zig), Dear ImGui (C++) |
| **Proyecto hermano** | zcatui (TUI library) |

### Descripción

**zcatgui** es una librería GUI immediate-mode para Zig con las siguientes características:

1. **Software Rendering por defecto** - Funciona en cualquier ordenador sin GPU
2. **Cross-platform** - Linux, Windows, macOS
3. **SSH compatible** - Funciona via X11 forwarding
4. **Sistema de Macros** - Grabación/reproducción de acciones (piedra angular)
5. **Sin dependencias pesadas** - Solo SDL2 para ventanas

### Filosofía

> "Máxima compatibilidad, mínimas dependencias, control total del usuario"

- Funciona en cualquier ordenador (viejo HP, nuevo Lenovo, servidor SSH)
- Software rendering primero, GPU opcional después
- Sistema de macros integrado desde el diseño
- Immediate mode = estado explícito, sin threading hell

---

## RUTAS IMPORTANTES

```bash
# Este proyecto
/mnt/cello2/arno/re/recode/zig/zcatgui/

# Proyecto hermano (TUI)
/mnt/cello2/arno/re/recode/zig/zcatui/

# Proyecto de referencia (usa Fyne, queremos replicar funcionalidad)
/mnt/cello2/arno/re/recode/go/simifactu/

# Normas del equipo
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/

# Compilador Zig 0.15.2
/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
```

---

## COMANDOS FRECUENTES

```bash
# Compilar
zig build

# Tests
zig build test

# Ejemplos (cuando estén implementados)
zig build hello
zig build button-demo
zig build macro-demo

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

---

## ARQUITECTURA

### Paradigma: Immediate Mode

```
┌─────────────────────────────────────────────────────────────┐
│                    IMMEDIATE MODE                           │
├─────────────────────────────────────────────────────────────┤
│  while (running) {                                          │
│      events = pollEvents();     // Input                    │
│      updateState(events);       // TÚ manejas estado        │
│      commands = drawUI(state);  // Genera comandos          │
│      render(commands);          // Dibuja                   │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘

vs Retained Mode (Fyne):
- Framework mantiene árbol de widgets
- Callbacks para cambios
- fyne.Do() para threading
- Estado oculto, sincronización compleja
```

### Capas de la Librería

```
┌─────────────────────────────────────────────────────────────┐
│  Capa 4: Widgets de alto nivel                              │
│  (Table, Panel, Select, Modal, etc.)                        │
├─────────────────────────────────────────────────────────────┤
│  Capa 3: Sistema de Macros                                  │
│  (Grabación, Reproducción, Inyección de teclas)             │
├─────────────────────────────────────────────────────────────┤
│  Capa 2: Core UI                                            │
│  (Context, Layout, Style, Input, Commands)                  │
├─────────────────────────────────────────────────────────────┤
│  Capa 1: Rendering                                          │
│  (Software Rasterizer, Framebuffer, Fonts)                  │
├─────────────────────────────────────────────────────────────┤
│  Capa 0: Backend                                            │
│  (SDL2 - ventanas, eventos, display)                        │
└─────────────────────────────────────────────────────────────┘
```

### Estructura de Archivos (ACTUAL)

```
zcatgui/
├── src/
│   ├── zcatgui.zig          # Entry point, re-exports
│   │
│   ├── core/
│   │   ├── context.zig      # ✅ Context, ID system, command pool
│   │   ├── layout.zig       # ✅ Rect, Constraint, LayoutState
│   │   ├── style.zig        # ✅ Color, Style, Theme
│   │   ├── input.zig        # ✅ Key, KeyEvent, MouseEvent, InputState
│   │   └── command.zig      # ✅ DrawCommand list
│   │
│   ├── widgets/
│   │   ├── widgets.zig      # ✅ Re-exports all widgets
│   │   ├── label.zig        # ✅ Static text display
│   │   ├── button.zig       # ✅ Clickable button
│   │   ├── text_input.zig   # ✅ Editable text field
│   │   ├── checkbox.zig     # ✅ Boolean toggle
│   │   ├── select.zig       # ✅ Dropdown selection
│   │   ├── list.zig         # ✅ Scrollable list
│   │   ├── focus.zig        # ✅ Focus management
│   │   ├── table.zig        # ✅ Editable table with scrolling
│   │   ├── split.zig        # ✅ HSplit/VSplit panels
│   │   ├── panel.zig        # ✅ Container with title bar
│   │   ├── modal.zig        # ✅ Modal dialogs (alert, confirm, input)
│   │   └── autocomplete.zig # ✅ ComboBox/AutoComplete widget
│   │
│   ├── render/
│   │   ├── software.zig     # ✅ SoftwareRenderer (ejecuta commands)
│   │   ├── framebuffer.zig  # ✅ Framebuffer RGBA
│   │   └── font.zig         # ✅ Bitmap font 8x8
│   │
│   ├── backend/
│   │   ├── backend.zig      # ✅ Backend interface (vtable)
│   │   └── sdl2.zig         # ✅ SDL2 implementation
│   │
│   └── macro/
│       └── macro.zig        # ✅ MacroRecorder, MacroPlayer, MacroStorage
│
├── examples/
│   ├── hello.zig            # ✅ Ejemplo básico de rendering
│   ├── macro_demo.zig       # ✅ Demo del sistema de macros
│   ├── widgets_demo.zig     # ✅ Demo de todos los widgets básicos
│   └── table_demo.zig       # ✅ Demo de Table, Split, Panel
│
├── docs/
│   ├── ARCHITECTURE.md      # Arquitectura detallada
│   └── research/
│       ├── GIO_UI_ANALYSIS.md
│       ├── IMMEDIATE_MODE_LIBS.md
│       └── SIMIFACTU_FYNE_ANALYSIS.md
│
├── build.zig
├── build.zig.zon
└── CLAUDE.md                # Este archivo
```

---

## SISTEMA DE MACROS (PIEDRA ANGULAR)

### Concepto

El sistema de macros permite **grabar y reproducir** todas las acciones del usuario.

**Principio**: Grabar teclas raw, no comandos abstractos.

```
Usuario pulsa: Tab, Tab, Enter, "texto", Escape
Grabamos:      [Tab, Tab, Enter, t, e, x, t, o, Escape]
Reproducimos:  Inyectamos exactamente esas teclas
```

### Por qué teclas raw (no comandos)

| Enfoque | Pros | Contras |
|---------|------|---------|
| **Teclas raw** | Simple, mínima memoria, reproducción exacta | Depende del estado inicial |
| Comandos semánticos | Más robusto | Complejo, más memoria, traducción bidireccional |

**Decisión**: Teclas raw (como Vim). Razones:
1. KISS - menos código = menos bugs
2. Vim lo hace así y funciona
3. El estado inicial es controlable

### Manejo del ratón

**Casi todo lo que hace el ratón se puede expresar como teclado**:

| Acción ratón | Equivalente teclado |
|--------------|---------------------|
| Click en botón | Tab hasta focus + Enter |
| Click en fila 5 | Flechas hasta fila 5 |
| Scroll down | PageDown o flechas |
| Drag splitter | Ctrl+flechas |

**Estrategia**:
1. Fase 1: Solo teclado (macros de teclas)
2. Fase 2: Mouse → traducir a teclas equivalentes

### API Propuesta

```zig
pub const MacroRecorder = struct {
    events: ArrayList(KeyEvent),
    recording: bool,

    pub fn start(self: *MacroRecorder) void;
    pub fn stop(self: *MacroRecorder) []const KeyEvent;
    pub fn record(self: *MacroRecorder, key: KeyEvent) void;
    pub fn save(self: *MacroRecorder, path: []const u8) !void;
    pub fn load(allocator: Allocator, path: []const u8) !MacroRecorder;
};

pub const MacroPlayer = struct {
    pub fn play(
        events: []const KeyEvent,
        inject_fn: *const fn(KeyEvent) void,
        delay_ms: u32,
    ) void;
};
```

### Casos de Uso

1. **Testing automatizado**: Grabar sesión → convertir en test
2. **Tutoriales**: Macros que se ejecutan paso a paso
3. **Repetición**: Grabar tarea repetitiva, asignar a hotkey
4. **Debugging**: "¿Cómo llegaste a este bug?" → envía el macro
5. **Demos**: Grabar demos que se reproducen en la app

---

## WIDGETS PRIORITARIOS

Basado en análisis de Simifactu (ver `docs/research/SIMIFACTU_FYNE_ANALYSIS.md`):

| # | Widget | Prioridad | Descripción |
|---|--------|-----------|-------------|
| 1 | **Table** | CRÍTICA | Edición in-situ, navegación teclado, dirty tracking |
| 2 | **Input** | CRÍTICA | Text entry con validación |
| 3 | **Select** | CRÍTICA | Dropdown selection |
| 4 | **Panel** | ALTA | Container con título y bordes |
| 5 | **Split** | ALTA | HSplit/VSplit draggable |
| 6 | **Button** | ALTA | Con estados disabled, importance |
| 7 | **Modal** | MEDIA | Diálogos modales |
| 8 | **List** | MEDIA | Lista seleccionable |
| 9 | **Checkbox** | MEDIA | Toggle boolean |
| 10 | **Label** | BAJA | Texto estático |

---

## RENDERING

### Software Rasterizer (Command List approach)

```zig
pub const DrawCommand = union(enum) {
    rect: struct {
        x: i32,
        y: i32,
        w: u32,
        h: u32,
        color: Color,
    },
    text: struct {
        x: i32,
        y: i32,
        text: []const u8,
        color: Color,
        font: *Font,
    },
    line: struct {
        x1: i32,
        y1: i32,
        x2: i32,
        y2: i32,
        color: Color,
    },
    clip: struct {
        x: i32,
        y: i32,
        w: u32,
        h: u32,
    },
    clip_end,
};
```

**Flujo**:
```
Widgets → Commands → Software Rasterizer → Framebuffer → SDL_Texture → Display
```

### Por qué Software Rendering

1. **Funciona SIEMPRE** - No depende de drivers GPU
2. **SSH compatible** - X11 forwarding funciona
3. **Máxima compatibilidad** - Desde HP viejo hasta Lenovo nuevo
4. **Simple de debugear** - Es solo un array de pixels

### Fonts

**Dos opciones soportadas**:
1. **Bitmap fonts** (embebidos) - Siempre funcionan, rápidos
2. **TTF** (stb_truetype) - Más flexible, opcional

---

## PLAN DE DESARROLLO

### Fase 0: Setup ✅ COMPLETADA
- [x] Crear estructura de directorios
- [x] build.zig con SDL2
- [x] CLAUDE.md
- [x] Documentación de investigación

### Fase 1: Core + Macros ✅ COMPLETADA
- [x] Context con event loop
- [x] Sistema de macros (grabación/reproducción teclas)
- [x] Software rasterizer básico (rects, text, lines)
- [x] SDL2 backend
- [x] Framebuffer RGBA

### Fase 2: Widgets Esenciales ✅ COMPLETADA
- [x] Label (static text)
- [x] Button (clickable, importance levels)
- [x] TextInput (editable text, cursor, selection)
- [x] Checkbox (boolean toggle)
- [x] Select (dropdown)
- [x] List (scrollable selection)
- [x] Focus management (FocusManager, FocusRing)

### Fase 3: Widgets Avanzados (PENDIENTE)
- [ ] Table con edición (CRÍTICO)
- [ ] Split panels (HSplit/VSplit draggable)
- [ ] Panel (container con título)
- [ ] Modal/Popup

### Fase 4: Pulido (PENDIENTE)
- [ ] Themes hot-reload
- [ ] TTF fonts (stb_truetype)
- [ ] Documentación completa
- [ ] Más examples

---

## REFERENCIAS Y RECURSOS

### Librerías estudiadas

| Librería | Lenguaje | LOC | Valor para nosotros |
|----------|----------|-----|---------------------|
| **microui** | C | 1,100 | Referencia arquitectura mínima |
| **DVUI** | Zig | 15,000 | Único ejemplo Zig native |
| **Dear ImGui** | C++ | 60,000 | API design, features |
| **Gio** | Go | - | Immediate mode moderno |
| **Nuklear** | C | 30,000 | Vertex buffer approach |

### Documentación detallada

- `docs/research/GIO_UI_ANALYSIS.md` - Análisis completo de Gio
- `docs/research/IMMEDIATE_MODE_LIBS.md` - Comparativa de librerías
- `docs/research/SIMIFACTU_FYNE_ANALYSIS.md` - Requisitos de Simifactu
- `docs/ARCHITECTURE.md` - Decisiones de arquitectura

### Links externos

- [microui GitHub](https://github.com/rxi/microui)
- [DVUI GitHub](https://github.com/david-vanderson/dvui)
- [Gio UI](https://gioui.org/)
- [Dear ImGui](https://github.com/ocornut/imgui)

---

## DECISIONES DE DISEÑO CONSENSUADAS

### 1. Immediate Mode vs Retained Mode
**Decisión**: Immediate Mode
**Razón**: Control total, sin threading hell (fyne.Do()), estado explícito

### 2. Software Rendering vs GPU
**Decisión**: Software por defecto, GPU opcional futuro
**Razón**: Máxima compatibilidad (SSH, HP viejo, cualquier driver)

### 3. Sistema de Macros
**Decisión**: Teclas raw, no comandos abstractos
**Razón**: Simple, como Vim, menos código = menos bugs

### 4. Backend inicial
**Decisión**: SDL2
**Razón**: Cross-platform probado, fácil de usar

### 5. Fonts
**Decisión**: Bitmap embebido + TTF opcional
**Razón**: Bitmap siempre funciona, TTF para flexibilidad

### 6. Enfoque de desarrollo
**Decisión**: Híbrido (estudiar DVUI/microui, implementar desde cero)
**Razón**: Aprender haciendo, control total, sin dependencias no deseadas

---

## RELACIÓN CON ZCATUI

**zcatui** (TUI) y **zcatgui** (GUI) son proyectos hermanos:

| Aspecto | zcatui | zcatgui |
|---------|--------|---------|
| Target | Terminal (ANSI) | Ventana gráfica |
| Rendering | Escape codes | Software rasterizer |
| Paradigma | Immediate mode | Immediate mode |
| Layout | Constraint-based | Constraint-based (reusar) |
| Style | Color/Modifier | Color/Style (reusar) |
| Widgets | 35 widgets | En desarrollo |

**Código a reutilizar de zcatui**:
- Sistema de Layout (Constraint, Flex)
- Sistema de Style (Color, Style)
- Conceptos de Focus
- Patterns de widgets

---

## EQUIPO

- **Usuario (Arno)**: Desarrollador principal
- **Claude**: Asistente de programación (Claude Code / Opus 4.5)

---

## NOTAS ZIG 0.15.2

```zig
// Sleep
std.Thread.sleep(ns)  // NO std.time.sleep

// ArrayList - CAMBIÓ en 0.15
// VIEJO: std.ArrayList(T).init(allocator)
// NUEVO: std.ArrayListUnmanaged(T) + pasar allocator a cada operación
var list: std.ArrayListUnmanaged(T) = .{};
defer list.deinit(allocator);
try list.append(allocator, item);  // allocator en cada append

// HashMap
var map = std.AutoHashMap(K, V).init(allocator);
defer map.deinit();

// Error handling
fn foo() !T { ... }
const result = try foo();
const result = foo() catch |err| { ... };

// File I/O - cambió en 0.15
const file = try std.fs.cwd().createFile(path, .{});
_ = try file.write("data");  // Directo

// stdout - cambió en 0.15
const stdout = std.fs.File.stdout();  // NO std.io.getStdOut()
// O usar std.debug.print() que es más simple

// build.zig.zon - requiere fingerprint
.{
    .fingerprint = 0x...,
    .name = .proyecto,  // enum literal, no string
    ...
}
```

---

## HISTORIAL

| Fecha | Versión | Cambios |
|-------|---------|---------|
| 2025-12-09 | v0.1.0 | Proyecto creado, estructura base, documentación |
| 2025-12-09 | v0.2.0 | Widgets Fase 2 completados (Label, Button, TextInput, Checkbox, Select, List, Focus) |
| 2025-12-09 | v0.3.0 | Widgets Fase 3 completados (Table editable, Split panels, Panel container) |
| 2025-12-09 | v0.3.5 | Keyboard integration: InputState ahora trackea teclas, Table responde a flechas/Enter/Escape/Tab/F2 |
| 2025-12-09 | v0.4.0 | Modal widget: diálogos modales (alert, confirm, input), plan extendido documentado |
| 2025-12-09 | v0.5.0 | AutoComplete widget, comparativa DVUI/Gio/zcatui en WIDGET_COMPARISON.md |
| 2025-12-09 | v0.6.0 | FASE 1 Optimización: FrameArena, ObjectPool, dirty rectangles, Benchmark suite |

---

## ESTADO ACTUAL

**El proyecto está en FASE 1 del Plan de Optimización - Fundamentos completados**

### Completado (✅):
- Estructura de directorios
- build.zig con SDL2
- Documentación de investigación
- Core: context (con FrameArena, dirty rectangles), layout, style, input, command
- Render: framebuffer, software renderer, font (bitmap 8x8)
- Backend: SDL2 (window, events, display)
- Macro: MacroRecorder, MacroPlayer, MacroStorage
- **Widgets**: Label, Button, TextInput, Checkbox, Select, List, Table, Split, Panel, Modal, AutoComplete, Slider, ScrollArea, Tabs, RadioButton (17 widgets)
- **Focus**: FocusManager, FocusRing
- **Lego Panels**: Panel, DataManager (Observer pattern)
- **Themes**: 5 themes (dark, light, high_contrast, nord, dracula)
- **TTF Fonts**: stb_truetype integration
- **Utils**: FrameArena (O(1) reset), ObjectPool, CommandPool, RingBuffer, Benchmark suite
- **Comparativa**: WIDGET_COMPARISON.md (vs DVUI, Gio)
- **Plan de desarrollo**: DEVELOPMENT_PLAN.md (9 fases para paridad DVUI/Gio)
- Examples: hello.zig, macro_demo.zig, widgets_demo.zig, table_demo.zig
- **123 tests pasando**

### FASE 1 - Fundamentos Sólidos ✅:
- [x] Arena allocator en Context (FrameArena con O(1) reset)
- [x] Object pooling (ObjectPool, CommandPool)
- [x] Dirty rectangles (invalidateRect, needsRedraw, mergeRects)
- [x] Benchmark suite (Timer, Benchmark, FrameTimer, AllocationTracker)
- [x] 123 tests pasando

### Próximas Fases (del DEVELOPMENT_PLAN.md):
- **FASE 2**: Widgets Faltantes (9 widgets para 100% paridad DVUI)
- **FASE 3**: Rendering Avanzado (GPU backend, vectores, gradientes)
- **FASE 4**: Sistema de Layout (Flexbox, Grid)
- **FASE 5**: Accesibilidad
- **FASE 6-9**: Internacionalización, Documentación, Testing, Pulido

### Verificar que funciona:
```bash
cd /mnt/cello2/arno/re/recode/zig/zcatgui
/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig build test  # 123 tests
/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig build
```

---

## PLAN DE TRABAJO EXTENDIDO

### Fase 4: Modal/Popup (PRÓXIMO)
- [ ] Modal widget (overlay que bloquea UI)
- [ ] Diálogos estándar: Confirm, Alert, Input
- [ ] Z-order/capas para popups

### Fase 5: Comparativa con Librerías de Referencia

#### 5.1 Comparar con DVUI (Zig) - Librería base de referencia
DVUI tiene ~30 widgets. Comparar y extraer lo que nos falta:

| Widget DVUI | zcatgui | Prioridad |
|-------------|---------|-----------|
| Button | ✅ | - |
| Checkbox | ✅ | - |
| TextInput | ✅ | - |
| Slider | ❌ | Media |
| ScrollArea | ❌ | Alta |
| Menu | ❌ | Alta |
| Dropdown | ✅ (Select) | - |
| TreeView | ❌ | Baja |
| Modal | ⏳ | Alta |
| Popup | ⏳ | Alta |
| Radio | ❌ | Media |
| ColorPicker | ❌ | Baja |
| ProgressBar | ❌ | Media |

#### 5.2 Comparar con Gio (Go)
Gio es immediate-mode moderno. Extraer patterns:
- [ ] Sistema de constraints/layout
- [ ] Gesture handling
- [ ] Animation system
- [ ] Theming approach

#### 5.3 Comparar con zcatui (nuestro TUI - 35 widgets)
Widgets de zcatui que deberíamos portar a GUI:

| Widget zcatui | zcatgui | Prioridad | Notas |
|---------------|---------|-----------|-------|
| input | ✅ | - | TextInput |
| select | ✅ | - | |
| checkbox | ✅ | - | |
| table | ✅ | - | |
| list | ✅ | - | |
| panel | ✅ | - | |
| **popup** | ⏳ | Alta | Modal/Popup |
| **menu** | ❌ | Alta | Menús contextuales |
| **tabs** | ❌ | Alta | Tab navigation |
| **tree** | ❌ | Media | TreeView |
| **calendar** | ❌ | Media | Date picker |
| **filepicker** | ❌ | Media | File browser |
| **dirtree** | ❌ | Media | Directory tree |
| progress | ❌ | Media | ProgressBar |
| gauge | ❌ | Baja | |
| sparkline | ❌ | Baja | |
| barchart | ❌ | Baja | |
| chart | ❌ | Baja | |
| canvas | ❌ | Baja | Custom drawing |
| markdown | ❌ | Baja | |
| syntax | ❌ | Baja | Code highlighting |
| viewport | ❌ | Media | Scrollable content |
| scroll | ❌ | Alta | ScrollArea |
| scrollbar | ❌ | Alta | |
| slider | ❌ | Media | |
| spinner | ❌ | Baja | Loading indicator |
| statusbar | ❌ | Media | |
| textarea | ❌ | Alta | Multiline input |
| tooltip | ❌ | Media | Hover help |
| help | ❌ | Baja | |
| logo | ❌ | Baja | |
| clear | ✅ | - | Implicit |
| block | ✅ | - | Panel/Container |
| paragraph | ✅ | - | Label |

### Fase 6: Widgets Específicos Simifactu

#### 6.1 AutoComplete/ComboBox Widget (CRÍTICO)
Widget usado en Simifactu para:
- Provincias (dropdown con búsqueda)
- Países (dropdown con búsqueda)
- Tipos IVA (dropdown con valores predefinidos)
- Poblaciones (autocomplete con sugerencias)

```zig
pub const AutoComplete = struct {
    /// Current text value
    text: []const u8,
    /// All available options
    options: []const []const u8,
    /// Filtered options based on text
    filtered: []const []const u8,
    /// Whether dropdown is open
    open: bool,
    /// Selected index in filtered list
    selected: i32,
    /// Allow custom values not in list
    allow_custom: bool,
    /// Callback when value changes
    on_change: ?*const fn([]const u8) void,
};
```

#### 6.2 AdvancedTable Analysis
Analizar `/mnt/cello2/arno/re/recode/go/simifactu/internal/ui/components/advanced_table/`:
- [ ] Sorting por columnas (click en header)
- [ ] Resize de columnas (drag)
- [ ] Column reordering (drag)
- [ ] Multi-select rows
- [ ] Copy/Paste cells
- [ ] Undo/Redo edits
- [ ] Calculated columns
- [ ] Column visibility toggle
- [ ] Export selected rows

#### 6.3 Sistema Lego Panels
Layout modular tipo Simifactu:
- [ ] Panel registry (panels registran su ID)
- [ ] Layout presets (Ctrl+1/2/3)
- [ ] Drag-and-drop panel reordering
- [ ] Panel minimize/maximize
- [ ] Save/restore layout state
- [ ] Panel communication (pub/sub)

### Fase 7: Features Avanzados

#### 7.1 Sistema de Themes
- [ ] Theme struct con todos los colores
- [ ] Hot-reload de themes
- [ ] Theme editor widget
- [ ] Persistencia de themes

#### 7.2 TTF Fonts
- [ ] Integrar stb_truetype
- [ ] Font atlas generation
- [ ] Multiple font sizes
- [ ] Font fallback chain

#### 7.3 Internacionalización
- [ ] String tables
- [ ] RTL support (futuro)

---

## WIDGETS ROADMAP VISUAL

```
COMPLETADOS (Fase 1-3.5):
✅ Label, Button, TextInput, Checkbox, Select, List
✅ Focus, Table, Split, Panel
✅ Keyboard integration

EN PROGRESO:
⏳ Modal/Popup

PRÓXIMOS (Fase 4-5):
📋 Menu, Tabs, ScrollArea, Scrollbar
📋 Radio, Slider, ProgressBar
📋 Textarea (multiline), Tooltip

SIMIFACTU-ESPECÍFICOS (Fase 6):
🎯 AutoComplete/ComboBox
🎯 AdvancedTable features (sort, resize, multi-select)
🎯 Lego Panel system

AVANZADOS (Fase 7):
🔮 Calendar, DatePicker
🔮 FilePicker, DirTree
🔮 Tree/TreeView
🔮 Themes hot-reload
🔮 TTF fonts
```

---

## ESTIMACIÓN DE TRABAJO

| Fase | Widgets/Features | Tiempo Est. |
|------|------------------|-------------|
| 4 | Modal/Popup | 2-3 días |
| 5.1 | Menu, Tabs, ScrollArea | 1 semana |
| 5.2 | Radio, Slider, Progress | 3-4 días |
| 5.3 | Textarea, Tooltip | 3-4 días |
| 6.1 | AutoComplete | 3-4 días |
| 6.2 | AdvancedTable | 1-2 semanas |
| 6.3 | Lego Panels | 1 semana |
| 7 | Themes, TTF | 1-2 semanas |
| **TOTAL** | | **6-8 semanas** |

---

## ARCHIVOS DE REFERENCIA

### Simifactu (Go/Fyne)
```
/mnt/cello2/arno/re/recode/go/simifactu/
├── internal/ui/components/advanced_table/  # AdvancedTable (2000+ LOC)
├── internal/ui/panels_v3/                  # Lego panel system
├── third_party/fynex-widgets/              # AutoComplete, DateEntry, etc.
└── internal/ui/dialogs/                    # Modal dialogs
```

### zcatui (Zig TUI - 35 widgets)
```
/mnt/cello2/arno/re/recode/zig/zcatui/src/widgets/
├── popup.zig       # Modal/Popup reference
├── menu.zig        # Menu widget
├── tabs.zig        # Tab navigation
├── tree.zig        # TreeView
├── calendar.zig    # Calendar/DatePicker
├── filepicker.zig  # File browser
└── ...
```

### DVUI (Zig GUI reference)
```
https://github.com/david-vanderson/dvui
```

### Gio (Go immediate-mode)
```
https://gioui.org/
docs/research/GIO_UI_ANALYSIS.md
```