docs: Reorganize CLAUDE.md with startup protocol
- Added "PROTOCOLO DE INICIO" section at the top - Clear instructions to read TEAM_STANDARDS first - Verification steps before starting work - Streamlined structure for quick reference - All essential info for next conversation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
73667a752e
commit
508bc37dca
1 changed files with 218 additions and 466 deletions
684
CLAUDE.md
684
CLAUDE.md
|
|
@ -1,26 +1,64 @@
|
|||
# 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
|
||||
> **IMPORTANTE PARA CLAUDE**: Lee la sección "PROTOCOLO DE INICIO" antes de hacer cualquier cosa.
|
||||
|
||||
---
|
||||
|
||||
## RESUMEN EJECUTIVO
|
||||
## PROTOCOLO DE INICIO (LEER PRIMERO)
|
||||
|
||||
**zcatui** es una librería TUI completa para Zig, equivalente a ratatui+crossterm de Rust pero en un solo paquete.
|
||||
### Paso 1: Leer normas del equipo
|
||||
```
|
||||
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/LAST_UPDATE.md
|
||||
```
|
||||
Este archivo contiene los cambios recientes en las normas de trabajo. Léelo para detectar actualizaciones.
|
||||
|
||||
### Estadísticas del Proyecto
|
||||
### 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: Verificar estado del proyecto
|
||||
```bash
|
||||
cd /mnt/cello2/arno/re/recode/zig/zcatui
|
||||
git status
|
||||
git log --oneline -3
|
||||
zig build test
|
||||
```
|
||||
|
||||
### Paso 4: Continuar trabajo
|
||||
Una vez verificado el estado, continúa desde donde se dejó o atiende la solicitud del usuario.
|
||||
|
||||
### Sobre TEAM_STANDARDS
|
||||
Es el repositorio centralizado con todas las normas de trabajo del equipo:
|
||||
- **LAST_UPDATE.md** - Cambios recientes (leer siempre primero)
|
||||
- **NORMAS_TRABAJO_CONSENSUADAS.md** - Metodología fundamental
|
||||
- **QUICK_REFERENCE.md** - Cheat sheet rápido
|
||||
- **INFRASTRUCTURE/** - Documentación de servidores, Zig 0.15 guía
|
||||
- **PROJECTS/** - Estado de todos los proyectos
|
||||
|
||||
---
|
||||
|
||||
## INFORMACIÓN DEL PROYECTO
|
||||
|
||||
**Nombre:** zcatui
|
||||
**Versión:** v2.0 - FEATURE COMPLETE
|
||||
**Última actualización:** 2025-12-08
|
||||
**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
|
||||
|
||||
### Descripción
|
||||
**zcatui** es una librería TUI completa para Zig, equivalente a ratatui+crossterm de Rust pero en un solo paquete. Permite crear interfaces de usuario en terminal con widgets, eventos, animaciones, themes, y más.
|
||||
|
||||
### Estadísticas
|
||||
| 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+ |
|
||||
| Archivos fuente | 60 archivos .zig |
|
||||
| Widgets | 27 widgets |
|
||||
| Módulos core | 16 módulos |
|
||||
| Tests | 186+ tests |
|
||||
| Examples | 11 demos ejecutables |
|
||||
|
||||
### Funcionalidades Principales
|
||||
- ✅ Renderizado immediate-mode con double buffering y diff
|
||||
|
|
@ -39,199 +77,27 @@
|
|||
|
||||
---
|
||||
|
||||
## ESTRUCTURA COMPLETA DEL PROYECTO
|
||||
## RUTAS IMPORTANTES
|
||||
|
||||
```
|
||||
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
|
||||
# Este proyecto
|
||||
/mnt/cello2/arno/re/recode/zig/zcatui/
|
||||
|
||||
# Normas del equipo (LEER SIEMPRE)
|
||||
/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
|
||||
|
||||
# Guía Zig 0.15 (cambios de API)
|
||||
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/INFRASTRUCTURE/ZIG_0.15_GUIA.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
## COMANDOS FRECUENTES
|
||||
|
||||
```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
|
||||
|
||||
|
|
@ -250,132 +116,142 @@ zig build clipboard-demo
|
|||
zig build menu-demo
|
||||
zig build form-demo
|
||||
zig build panel-demo
|
||||
|
||||
# Git
|
||||
git status
|
||||
git add -A && git commit -m "mensaje"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## THEMES DISPONIBLES
|
||||
## ESTRUCTURA DEL PROYECTO
|
||||
|
||||
```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();
|
||||
```
|
||||
zcatui/
|
||||
├── src/
|
||||
│ ├── root.zig # Entry point, re-exports
|
||||
│ │
|
||||
│ ├── ─── CORE ───
|
||||
│ ├── buffer.zig # Buffer, Cell, Rect, Symbol
|
||||
│ ├── style.zig # Color, Style, Modifier
|
||||
│ ├── text.zig # Text, Line, Span
|
||||
│ ├── layout.zig # Layout, Constraint
|
||||
│ ├── terminal.zig # Terminal abstraction
|
||||
│ │
|
||||
│ ├── ─── EVENTOS ───
|
||||
│ ├── event.zig # Event, KeyEvent, MouseEvent
|
||||
│ ├── event/
|
||||
│ │ ├── reader.zig # EventReader
|
||||
│ │ └── parse.zig # Escape parser
|
||||
│ │
|
||||
│ ├── ─── FEATURES ───
|
||||
│ ├── focus.zig # FocusRing, FocusManager
|
||||
│ ├── theme.zig # 10 themes predefinidos
|
||||
│ ├── animation.zig # Easing, Timer
|
||||
│ ├── cursor.zig # Cursor control
|
||||
│ ├── clipboard.zig # OSC 52
|
||||
│ ├── hyperlink.zig # OSC 8
|
||||
│ ├── notification.zig # OSC 9/777
|
||||
│ ├── image.zig # Kitty/iTerm2
|
||||
│ ├── lazy.zig # RenderCache, Throttle
|
||||
│ ├── unicode.zig # charWidth, stringWidth
|
||||
│ ├── termcap.zig # Terminal detection
|
||||
│ │
|
||||
│ ├── ─── BACKEND ───
|
||||
│ ├── backend/
|
||||
│ │ └── backend.zig # ANSI sequences
|
||||
│ │
|
||||
│ ├── ─── SYMBOLS ───
|
||||
│ ├── symbols/ # line, border, block, bar, braille...
|
||||
│ │
|
||||
│ ├── ─── WIDGETS (27) ───
|
||||
│ ├── widgets/
|
||||
│ │ ├── block.zig # Block (borders, titles)
|
||||
│ │ ├── paragraph.zig # Text wrapping
|
||||
│ │ ├── list.zig # Selectable list
|
||||
│ │ ├── table.zig # Multi-column table
|
||||
│ │ ├── gauge.zig # Progress bars
|
||||
│ │ ├── tabs.zig # Tab navigation
|
||||
│ │ ├── sparkline.zig # Mini graphs
|
||||
│ │ ├── scrollbar.zig # Scroll indicator
|
||||
│ │ ├── barchart.zig # Bar charts
|
||||
│ │ ├── canvas.zig # Drawing
|
||||
│ │ ├── chart.zig # Graphs with axes
|
||||
│ │ ├── calendar.zig # Monthly calendar
|
||||
│ │ ├── clear.zig # Clear area
|
||||
│ │ ├── input.zig # Text input
|
||||
│ │ ├── textarea.zig # Multi-line editor
|
||||
│ │ ├── popup.zig # Popup + Modal
|
||||
│ │ ├── menu.zig # Menu, MenuBar, ContextMenu
|
||||
│ │ ├── tooltip.zig # Tooltips
|
||||
│ │ ├── tree.zig # Tree view
|
||||
│ │ ├── filepicker.zig # File picker
|
||||
│ │ ├── scroll.zig # ScrollView, VirtualList
|
||||
│ │ ├── panel.zig # Panel, TabbedPanel
|
||||
│ │ ├── checkbox.zig # Checkbox, RadioGroup
|
||||
│ │ ├── select.zig # Select dropdown
|
||||
│ │ ├── slider.zig # Slider
|
||||
│ │ └── statusbar.zig # StatusBar, Toast
|
||||
│ │
|
||||
│ └── ─── TESTS ───
|
||||
│ └── tests/ # Test suite
|
||||
│
|
||||
├── examples/ # 11 demos
|
||||
├── docs/ # ARCHITECTURE.md, WIDGETS.md, API.md
|
||||
├── build.zig
|
||||
├── README.md
|
||||
└── CLAUDE.md # Este archivo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FOCUS MANAGEMENT
|
||||
## NOTAS TÉCNICAS ZIG 0.15.2
|
||||
|
||||
### Cambios de API importantes
|
||||
```zig
|
||||
const FocusManager = zcatui.FocusManager;
|
||||
const FocusRing = zcatui.FocusRing;
|
||||
// Campos de Style
|
||||
style.foreground // NO style.fg
|
||||
style.background // NO style.bg
|
||||
|
||||
var manager = FocusManager{};
|
||||
// Sleep
|
||||
std.Thread.sleep(ns) // NO std.time.sleep
|
||||
|
||||
// Crear rings (grupos de widgets)
|
||||
const main_ring = manager.createRing("main");
|
||||
const modal_ring = manager.createRing("modal");
|
||||
// Cell
|
||||
cell.symbol // NO cell.char
|
||||
|
||||
// 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");
|
||||
// Modifiers
|
||||
style.add_modifier(.{ .bold = true }) // NO addModifier
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UNICODE WIDTH
|
||||
|
||||
### Patrones comunes
|
||||
```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
|
||||
// Builder pattern
|
||||
pub fn setOption(self: Widget, value: T) Widget {
|
||||
var w = self;
|
||||
w.option = value;
|
||||
return w;
|
||||
}
|
||||
|
||||
// Features
|
||||
caps.hyperlinks // OSC 8 support
|
||||
caps.images // Kitty/Sixel
|
||||
caps.clipboard // OSC 52
|
||||
caps.unicode // UTF-8 support
|
||||
caps.styled_underline // Curly underlines
|
||||
// Render pattern
|
||||
pub fn render(self: Widget, area: Rect, buf: *Buffer) void {
|
||||
if (area.isEmpty()) return;
|
||||
// ...
|
||||
}
|
||||
|
||||
// Adaptar colores al terminal
|
||||
const adapted = termcap.adaptColor(caps, r, g, b);
|
||||
// Focus interface (vtable)
|
||||
pub const Focusable = struct {
|
||||
ptr: *anyopaque,
|
||||
vtable: *const VTable,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
- **Usuario (Arno)**: Desarrollador independiente
|
||||
- **Claude**: Asistente de programación (Claude Code / Opus 4.5)
|
||||
|
||||
### Cómo Trabajamos
|
||||
|
|
@ -384,197 +260,73 @@ const adapted = termcap.adaptColor(caps, r, g, b);
|
|||
- Documentación inline con `///` doc comments
|
||||
- Código idiomático Zig (snake_case, error handling explícito)
|
||||
- Sin dependencias externas
|
||||
- Commits descriptivos con emoji 🤖
|
||||
|
||||
### 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ó
|
||||
### Reglas Importantes
|
||||
1. **Siempre leer TEAM_STANDARDS/LAST_UPDATE.md** al inicio
|
||||
2. **Verificar `zig build test`** antes de commit
|
||||
3. **No ejecutar binarios/servidores** que queden como zombies
|
||||
4. **Commits solo cuando el usuario lo pida**
|
||||
|
||||
---
|
||||
|
||||
## CONTROL DE VERSIONES
|
||||
## OTROS PROYECTOS ZIG
|
||||
|
||||
| Proyecto | Descripción | Path |
|
||||
|----------|-------------|------|
|
||||
| zcatui | TUI library (este) | `/mnt/cello2/arno/re/recode/zig/zcatui` |
|
||||
| service-monitor | Monitor HTTP/TCP | `/mnt/cello2/arno/re/recode/zig/service-monitor` |
|
||||
| zsqlite | SQLite wrapper | `/mnt/cello2/arno/re/recode/zig/zsqlite` |
|
||||
| zpdf | PDF generator | `/mnt/cello2/arno/re/recode/zig/zpdf` |
|
||||
|
||||
---
|
||||
|
||||
## REPOSITORIOS
|
||||
|
||||
```bash
|
||||
# Remote
|
||||
# Este proyecto
|
||||
git@git.reugenio.com:reugenio/zcatui.git
|
||||
|
||||
# Estado actual
|
||||
git log --oneline -5
|
||||
# TEAM_STANDARDS
|
||||
git@git.reugenio.com:reugenio/development-standards.git
|
||||
|
||||
# Servidor Git
|
||||
git.reugenio.com (Forgejo)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OTROS PROYECTOS DEL ECOSISTEMA
|
||||
## HISTORIAL RECIENTE
|
||||
|
||||
### 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/` |
|
||||
| Versión | Fecha | Cambios |
|
||||
|---------|-------|---------|
|
||||
| v2.0 | 2025-12-08 | Focus, themes, unicode, termcap, 186+ tests |
|
||||
| v1.4 | 2025-12-08 | Form widgets, panels, scroll, tree |
|
||||
| v1.3 | 2025-12-08 | Menus, modals, animation, clipboard |
|
||||
| v1.2 | 2025-12-08 | Sistema eventos |
|
||||
| v1.0 | 2025-12-08 | 13 widgets iniciales |
|
||||
|
||||
---
|
||||
|
||||
## RECURSOS Y REFERENCIAS
|
||||
## ESTADO ACTUAL
|
||||
|
||||
### ratatui (Rust) - Referencia principal
|
||||
- Repo: https://github.com/ratatui/ratatui
|
||||
- Docs: https://docs.rs/ratatui/latest/ratatui/
|
||||
- Website: https://ratatui.rs/
|
||||
**El proyecto está FEATURE COMPLETE (v2.0)**
|
||||
|
||||
### Zig
|
||||
- Docs 0.15: https://ziglang.org/documentation/0.15.0/std/
|
||||
- Guía migración: `TEAM_STANDARDS/INFRASTRUCTURE/ZIG_0.15_GUIA.md`
|
||||
- ✅ Todos los widgets implementados
|
||||
- ✅ Todos los tests pasando (186+)
|
||||
- ✅ Documentación completa
|
||||
- ✅ Examples funcionando
|
||||
|
||||
### 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
|
||||
**Posibles mejoras futuras (opcionales):**
|
||||
- Performance: SIMD para 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
|
||||
## REFERENCIAS
|
||||
|
||||
```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
|
||||
```
|
||||
- ratatui (Rust): https://ratatui.rs/
|
||||
- Zig docs 0.15: https://ziglang.org/documentation/0.15.0/std/
|
||||
- ANSI codes: https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797
|
||||
|
|
|
|||
Loading…
Reference in a new issue