From 73667a752e3ffce847aa376c8ba653b6ab8ffa69 Mon Sep 17 00:00:00 2001 From: reugenio Date: Mon, 8 Dec 2025 19:37:58 +0100 Subject: [PATCH] docs: Update CLAUDE.md with v2.0 complete documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Full project status: v2.0 FEATURE COMPLETE - 60 source files, 27 widgets, 186+ tests - Detailed module breakdown (core, events, features, widgets) - Examples and commands reference - Focus management, themes, unicode, termcap documentation - Team methodology and workflow notes - Historical development timeline - Quick reference section for next conversations 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 907 +++++++++++++++++++++++++++--------------------------- 1 file changed, 461 insertions(+), 446 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d349f0c..ccba8af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,376 +1,241 @@ # 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**: v1.3 - Widgets completos + Animaciones + Clipboard + Menus - -## Descripción del Proyecto - -**zcatui** es una librería para crear interfaces de usuario en terminal (TUI) en Zig puro, combinando las capacidades de ratatui (renderizado) y crossterm (eventos) de Rust. - -**Objetivo**: Proveer una API idiomática Zig para construir aplicaciones TUI interactivas con widgets, layouts, estilos, y manejo de eventos de teclado/ratón, manteniendo la filosofía de Zig: simple, explícito, y sin magia. - -**Nombre**: "zcat" + "ui" (un guiño a ratatui y la mascota de Zig) - -**Diferencia con Rust**: En Rust, ratatui y crossterm son librerías separadas. En zcatui, todo está integrado en una sola librería. +> **Estado**: Librería completa y lista para producción --- -## Estado Actual del Proyecto +## RESUMEN EJECUTIVO -### Implementación Completa (v1.3) - 2025-12-08 +**zcatui** es una librería TUI completa para Zig, equivalente a ratatui+crossterm de Rust pero en un solo paquete. -| Componente | Estado | Archivo | -|------------|--------|---------| -| **Core** | ✅ Completo | | -| Style + Color | ✅ | `src/style.zig` | -| Buffer + Cell | ✅ | `src/buffer.zig` | -| Text + Span + Line | ✅ | `src/text.zig` | -| Layout + Constraint | ✅ | `src/layout.zig` | -| Terminal | ✅ | `src/terminal.zig` | -| Backend ANSI | ✅ | `src/backend/` | -| **Eventos (crossterm-style)** | ✅ Completo | | -| Event, KeyEvent, MouseEvent | ✅ | `src/event.zig` | -| EventReader + polling | ✅ | `src/event/reader.zig` | -| Escape sequence parser | ✅ | `src/event/parse.zig` | -| Cursor control | ✅ | `src/cursor.zig` | -| **Symbols** | ✅ Completo | `src/symbols/` | -| Line drawing | ✅ | `line.zig` | -| Border sets | ✅ | `border.zig` | -| Block chars | ✅ | `block.zig` | -| Bar chars | ✅ | `bar.zig` | -| Braille patterns | ✅ | `braille.zig` | -| Half-block | ✅ | `half_block.zig` | -| Scrollbar symbols | ✅ | `scrollbar.zig` | -| Markers | ✅ | `marker.zig` | -| **Widgets** | ✅ Completo (17 widgets) | `src/widgets/` | -| Block | ✅ | `block.zig` | -| Paragraph | ✅ | `paragraph.zig` | -| List | ✅ | `list.zig` | -| Table | ✅ | `table.zig` | -| Gauge + LineGauge | ✅ | `gauge.zig` | -| Tabs | ✅ | `tabs.zig` | -| Sparkline | ✅ | `sparkline.zig` | -| Scrollbar | ✅ | `scrollbar.zig` | -| BarChart | ✅ | `barchart.zig` | -| Canvas | ✅ | `canvas.zig` | -| Chart | ✅ | `chart.zig` | -| Calendar (Monthly) | ✅ | `calendar.zig` | -| Clear | ✅ | `clear.zig` | -| Input (readline-style) | ✅ | `input.zig` | -| Popup | ✅ | `popup.zig` | -| Modal | ✅ | `popup.zig` | -| Menu + MenuBar | ✅ | `menu.zig` | -| **Extras** | ✅ Completo | | -| Animation system | ✅ | `src/animation.zig` | -| Clipboard (OSC 52) | ✅ | `src/clipboard.zig` | +### 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+ | -### Examples (10 demos) - -| Ejemplo | Descripción | Comando | -|---------|-------------|---------| -| hello | Minimal TUI app | `zig build hello` | -| events_demo | Keyboard/mouse events | `zig build events-demo` | -| list_demo | Lista navegable | `zig build list-demo` | -| table_demo | Tabla con selección | `zig build table-demo` | -| dashboard | Demo completo | `zig build dashboard` | -| input_demo | Input readline-style | `zig build input-demo` | -| animation_demo | Easing functions | `zig build animation-demo` | -| clipboard_demo | OSC 52 clipboard | `zig build clipboard-demo` | -| menu_demo | MenuBar + Modal | `zig build menu-demo` | - -### Tests - -| Módulo | Tests | -|--------|-------| -| Widgets (13 originales) | 103 | -| Animation | 12 | -| Clipboard | 8 | -| Popup | 5 | -| Menu | 5 | -| Events | 29 | -| **Total** | **~160+** | +### 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 --- -## Widgets Nuevos (v1.3) - -### Input (readline-style) -Input de texto con edición avanzada. -```zig -var state = InputState.init(allocator); -defer state.deinit(); - -const input = Input.init() - .setBlock(Block.init().title("Name").borders(Borders.all)) - .setPlaceholder("Enter your name..."); -input.render(area, buf, &state); - -// Keyboard handling -if (state.handleKey(key_event)) { - // Key was consumed by input -} -``` - -**Features:** -- Cursor movement (←→, Home, End) -- Word navigation (Ctrl+←→) -- Delete (Backspace, Del, Ctrl+W, Ctrl+U, Ctrl+K) -- Kill/yank (Ctrl+K, Ctrl+Y) -- History (↑↓) -- Unicode support - -### Popup -Overlay flotante. -```zig -const popup = Popup.init() - .setSize(40, 10) - .setBlock(Block.init().title("Info").borders(Borders.all)) - .setDimBackground(true) - .center(); -popup.render(area, buf); -``` - -### Modal -Diálogo con botones. -```zig -var modal = Modal.init() - .setTitle("Confirm") - .setMessage(&.{"Are you sure?"}) - .setButtons(&.{ - .{ .label = "OK" }, - .{ .label = "Cancel" }, - }); -modal.render(area, buf); - -// Navigation -modal.focusNext(); // Tab -modal.focusPrev(); // Shift+Tab -const selected = modal.getFocusedButton(); -``` - -**Helpers:** -```zig -const confirm = confirmDialog("Title", &.{"Message"}); -const alert = alertDialog("Title", &.{"Message"}); -const yesno = yesNoCancelDialog("Title", &.{"Message"}); -``` - -### Menu + MenuBar -Sistema de menús. -```zig -const file_menu = Menu.init().setItems(&.{ - MenuItem.action("New", 'n').setShortcut("Ctrl+", 'N'), - MenuItem.action("Open", 'o'), - MenuItem.separator(), - MenuItem.action("Exit", 'q'), -}); - -var menu_bar = MenuBar.init().setItems(&.{ - MenuBarItem.init("File", file_menu), - MenuBarItem.init("Edit", edit_menu), -}); - -menu_bar.render(area, buf); - -// Navigation -menu_bar.selectNext(); // → -menu_bar.selectPrev(); // ← -menu_bar.openSelected(); // Enter -menu_bar.closeMenus(); // Esc - -// Dropdown -if (menu_bar.open_menu) |idx| { - const dropdown_area = menu_bar.getDropdownArea(area, idx); - var menu = getCurrentMenu(); - menu.render(dropdown_area, buf); -} -``` - -**MenuItem types:** -- `.action` - Clickable action -- `.separator` - Visual separator -- `.submenu` - Opens nested menu -- `.toggle` - Checkbox option - ---- - -## Sistema de Animaciones - -### Easing Functions -```zig -const Easing = zcatui.Easing; - -// Available: -Easing.linear -Easing.easeIn / easeOut / easeInOut -Easing.easeInCubic / easeOutCubic / easeInOutCubic -Easing.easeInExpo / easeOutExpo -Easing.easeOutBounce -Easing.easeOutElastic -Easing.easeOutBack -``` - -### Animation -```zig -var anim = Animation.init(0, 100, 2000) // 0→100 over 2 seconds - .setEasing(Easing.easeOutBounce) - .setRepeat(-1) // Infinite - .setPingPong(true); // Reverse on repeat - -// In game loop: -anim.advance(delta_ms); -const value = anim.getValue(); // f64 -const percent = anim.getValueU16(); // u16 (0-65535) -``` - -### Timer -```zig -var timer = Timer.repeating(1000); // 1 second - -if (timer.advance(delta_ms)) { - // Timer triggered! -} -``` - -### AnimationGroup -```zig -var group = AnimationGroup.parallel(&animations); -// or -var group = AnimationGroup.sequential(&animations); - -group.advance(delta_ms); -if (group.isComplete()) { ... } -``` - ---- - -## Clipboard (OSC 52) - -```zig -const clipboard = zcatui.clipboard; -const writer = term.backend.stdout.deprecatedWriter(); - -// Copy to system clipboard -try clipboard.copy(allocator, writer, "Hello!"); - -// Copy to X11 primary selection -try clipboard.copySmallTo(writer, "Text", .primary); - -// Copy to both -try clipboard.copySmallTo(writer, "Text", .both); - -// Clear clipboard -try clipboard.clear(writer); -``` - -**Terminal support:** xterm, iTerm2, kitty, alacritty, WezTerm, foot -**tmux:** Enable with `set -g set-clipboard on` - ---- - -## Arquitectura - -### Diseño: Immediate Mode Rendering - -``` -┌─────────────┐ ┌────────┐ ┌──────────┐ -│ Application │───▶│ Buffer │───▶│ Terminal │ -│ (widgets) │ │ (cells)│ │ (output) │ -└─────────────┘ └────────┘ └──────────┘ -``` - -- Cada frame, la aplicación renderiza TODOS los widgets al buffer -- El buffer se compara con el anterior (diff) -- Solo se envían cambios a la terminal (eficiencia) - -### Estructura de Archivos +## ESTRUCTURA COMPLETA DEL PROYECTO ``` zcatui/ ├── src/ -│ ├── root.zig # Entry point, re-exports públicos -│ ├── terminal.zig # Terminal + eventos integrados -│ ├── buffer.zig # Buffer + Cell + Rect -│ ├── layout.zig # Layout, Constraint, Direction -│ ├── style.zig # Color, Style, Modifier -│ ├── text.zig # Text, Line, Span, Alignment -│ ├── event.zig # Event, KeyEvent, MouseEvent, KeyCode -│ ├── cursor.zig # Cursor control (shapes, position) -│ ├── animation.zig # Easing, Animation, Timer -│ ├── clipboard.zig # OSC 52 clipboard support +│ ├── 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 + polling -│ │ └── parse.zig # Escape sequence parser +│ │ ├── 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 backend +│ │ └── backend.zig # ANSI escape sequences +│ │ +│ ├── ─── SYMBOLS ─── │ ├── symbols/ -│ │ ├── symbols.zig # Re-exports -│ │ ├── line.zig # Line drawing characters -│ │ ├── border.zig # Border sets -│ │ ├── block.zig # Block elements -│ │ ├── bar.zig # Bar characters -│ │ ├── braille.zig # Braille patterns (256) -│ │ ├── half_block.zig # Half-block chars -│ │ ├── scrollbar.zig # Scrollbar symbols -│ │ └── marker.zig # Chart markers -│ └── 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 # Progress bars (Gauge + LineGauge) -│ ├── 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) -│ ├── chart.zig # Line/scatter/bar graphs -│ ├── calendar.zig # Monthly calendar -│ ├── clear.zig # Clear/reset area -│ ├── input.zig # Readline-style input -│ ├── popup.zig # Popup + Modal -│ └── menu.zig # Menu + MenuBar -├── examples/ -│ ├── hello.zig -│ ├── events_demo.zig -│ ├── list_demo.zig -│ ├── table_demo.zig -│ ├── dashboard.zig -│ ├── input_demo.zig -│ ├── animation_demo.zig -│ ├── clipboard_demo.zig -│ └── menu_demo.zig +│ │ ├── 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 -│ ├── WIDGETS.md -│ └── API.md +│ ├── ARCHITECTURE.md # Arquitectura técnica +│ ├── WIDGETS.md # Guía de widgets +│ └── API.md # Referencia rápida +│ ├── build.zig -└── CLAUDE.md +├── README.md # Documentación pública +└── CLAUDE.md # Este archivo ``` --- -## Stack Técnico +## MÓDULOS DETALLADOS -| 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) | -| **Sin dependencias externas** | Solo stdlib de Zig | -| **Target** | Linux primario, cross-platform objetivo | +### 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 +## COMANDOS ```bash -# Compilar todo +# 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 +# Tests (186+ tests) zig build test # Ejecutar ejemplos @@ -383,83 +248,142 @@ zig build input-demo zig build animation-demo zig build clipboard-demo zig build menu-demo +zig build form-demo +zig build panel-demo ``` --- -## Funcionalidades Pendientes (Roadmap) +## THEMES DISPONIBLES -### Prioridad Alta -- [ ] **Scrollable containers** - Viewport para contenido largo -- [ ] **Textarea widget** - Input multilínea con scroll +```zig +const Theme = zcatui.Theme; -### Prioridad Media -- [ ] **Sistema LEGO panels** - Patrones de simifactu-fyne (isDirty, composites) -- [ ] **Context menu** - Menú contextual (right-click) -- [ ] **Tooltips** - Información emergente +// 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; -### Prioridad Baja -- [ ] **Hyperlinks OSC 8** - Links clickeables en terminal -- [ ] **Image protocol** - Kitty/iTerm2 inline images -- [ ] **Notifications OSC 9/777** - Desktop notifications -- [ ] **Tree widget** - Árbol expandible/colapsable -- [ ] **File picker** - Selección de archivos - -### Performance -- [ ] Lazy rendering para widgets grandes -- [ ] Pooling de memoria para cells -- [ ] SIMD para operaciones de buffer masivas - -### Documentación -- [ ] Tutorial paso a paso -- [ ] API reference generada -- [ ] Más ejemplos +// Uso +const style = theme.primaryStyle(); +const error_style = theme.errorStyle(); +const selection_style = theme.selectionStyle(); +``` --- -## Estudio: Sistema LEGO Panels (simifactu-fyne) +## FOCUS MANAGEMENT -Se realizó un análisis completo del sistema de paneles de simifactu-fyne. Los patrones clave son: +```zig +const FocusManager = zcatui.FocusManager; +const FocusRing = zcatui.FocusRing; -### 1. Autonomous Panel Interface -Cada panel se auto-gestiona: conoce su ID, tipo, sabe construir su UI y refrescarse. +var manager = FocusManager{}; -### 2. isDirty Pattern -Desacopla notificación (O(1)) de actualización (O(n)): -- Observer notifica → solo pone flag `isDirty = true` -- Refresh loop verifica `isDirty()` -- Panel actualiza solo si necesario -- Flags granulares: `dirtyData`, `dirtyColors`, `dirtyConfig`, `dirtySorting` +// Crear rings (grupos de widgets) +const main_ring = manager.createRing("main"); +const modal_ring = manager.createRing("modal"); -### 3. Composición LEGO -Paneles pequeños se combinan en layouts: -- HSplit: Dos paneles lado a lado -- VSplit/Border: Top/center/bottom -- Composites: Paneles que contienen otros paneles +// Añadir widgets focusables +_ = main_ring.?.add(widget1.focusable()); +_ = main_ring.?.add(widget2.focusable()); -### 4. WindowComposer -Orquestador que maneja: -- Registro de paneles por posición (left, center, right, top) -- Navegación de foco (NextPanel, PreviousPanel) -- Broadcasting de eventos +// Navegación +_ = manager.focusNext(); // Tab +_ = manager.focusPrev(); // Shift+Tab +_ = manager.focusFirst(); // Home +_ = manager.focusLast(); // End -### 5. Callbacks para comunicación -```go -listPanel.OnItemSelected = func(item Item) { - detailPanel.LoadItem(item) +// 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 } -``` -**Archivos de referencia:** -- `/mnt/cello2/arno/re/recode/go/simifactu-fyne/internal/ui/panels_v3/` +// 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); +``` --- -## Equipo y Metodología +## 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**: Desarrollador independiente, proyectos comerciales propios -- **Claude**: Asistente de programación (Claude Code) +- **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 @@ -469,97 +393,188 @@ listPanel.OnItemSelected = func(item Item) { ``` **Archivos clave a leer**: -- `LAST_UPDATE.md` - **LEER PRIMERO** - Cambios recientes en normas -- `NORMAS_TRABAJO_CONSENSUADAS.md` - Metodología fundamental -- `QUICK_REFERENCE.md` - Cheat sheet rápido -- `INFRASTRUCTURE/` - Documentación de servidores +| 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 recientes) +1. **Leer** `TEAM_STANDARDS/LAST_UPDATE.md` (detectar cambios) 2. **Leer** este archivo `CLAUDE.md` -3. **Verificar** estado del proyecto (`git status`, `zig build`) +3. **Verificar** estado (`git status`, `zig build test`) 4. **Continuar** desde donde se dejó --- -## Control de Versiones +## CONTROL DE VERSIONES ```bash # Remote -git remote: git@git.reugenio.com:reugenio/zcatui.git +git@git.reugenio.com:reugenio/zcatui.git -# Comandos frecuentes -zig build # Compilar -zig build test # Tests -zig build test --summary all # Tests con detalles +# Estado actual +git log --oneline -5 ``` --- -## Recursos y Referencias +## OTROS PROYECTOS DEL ECOSISTEMA -### ratatui (Rust) - Referencia de implementación +### 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/ -- Clone local: `/mnt/cello2/arno/re/recode/ratatui-reference/` ### 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 -- Referencia: https://en.wikipedia.org/wiki/ANSI_escape_code -- Colores: https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797 +- https://en.wikipedia.org/wiki/ANSI_escape_code +- https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797 --- -## Historial de Desarrollo +## 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) -### 2025-12-08 - v1.3 (Widgets avanzados + Extras) **Widgets nuevos:** -- Input: Readline-style con cursor, word nav, kill/yank, history, Unicode -- Popup: Overlay flotante con backdrop dimming -- Modal: Diálogo con título, mensaje, botones navegables -- Menu: Dropdown menu con shortcuts -- MenuBar: Barra horizontal con dropdowns +- Checkbox, RadioGroup, CheckboxGroup +- Select, MultiSelect +- Slider, RangeSlider +- StatusBar, Toast, ToastManager +- Panel, PanelSplit, TabbedPanel, DockingPanel -**Sistemas nuevos:** -- Animation: Easing functions, Animation, AnimationGroup, Timer -- Clipboard: OSC 52 copy/paste support +**Features:** +- Tooltip + TooltipManager +- Tree widget +- FilePicker +- ScrollView, VirtualList, InfiniteScroll -**Ejemplos nuevos:** -- list_demo.zig, table_demo.zig, dashboard.zig -- input_demo.zig, animation_demo.zig -- clipboard_demo.zig, menu_demo.zig +### 2025-12-08 - v1.3 (Menus + Modals) -**Estudio:** -- Análisis completo del sistema LEGO panels de simifactu-fyne +**Widgets nuevos:** +- Input (readline-style) +- Popup, Modal +- Menu, MenuBar, ContextMenu -### 2025-12-08 - v1.2 (Eventos - crossterm-style) -- Sistema de eventos integrado (teclado + ratón) -- Event, KeyEvent, MouseEvent, KeyCode types -- EventReader con polling y timeout -- Parser de escape sequences (CSI, SS3, SGR mouse, X10 mouse) -- Cursor control (shapes, blinking, save/restore) -- Terminal integrado: pollEvent(), enableMouseCapture(), enableFocusChange() -- Ejemplo interactivo: events_demo.zig +**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: tipo compacto UTF-8 (4 bytes max) -- Buffer.diff(): renderizado diferencial eficiente -- Cell.eql(): comparación optimizada -- Buffer.resize(): redimensionado con preservación -- writeSymbol(): output UTF-8 directo +- Symbol type compacto +- Buffer diff rendering +- Optimizaciones -### 2025-12-08 - v1.0 (Implementación Completa) -- Implementados todos los widgets de ratatui (13 widgets) -- Sistema de símbolos completo (braille, half-block, borders, etc.) -- 103+ tests en widgets -- Documentación completa (ARCHITECTURE.md, WIDGETS.md, API.md) +### 2025-12-08 - v1.0 (Implementación inicial) +- 13 widgets base (ratatui equivalents) +- Sistema de símbolos +- 103+ tests iniciales -### 2025-12-08 - Inicio del Proyecto -- Creación de CLAUDE.md +### 2025-12-08 - Inicio +- Creación del proyecto - Definición de arquitectura -- Estructura inicial del proyecto + +--- + +## 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 +```