diff --git a/CLAUDE.md b/CLAUDE.md index 5a5532c..7e8131e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,8 @@ ### Paso 3: Leer documentación ``` -REFERENCE.md # ⭐ MANUAL DE REFERENCIA COMPLETO (1370 líneas) +REFERENCE.md # ⭐ MANUAL DE REFERENCIA COMPLETO +docs/research/DVUI_AUDIT_2025-12-17.md # ⭐ AUDITORÍA DVUI - TAREA PENDIENTE docs/DEVELOPMENT_PLAN.md # Plan de desarrollo por fases docs/MOBILE_WEB_BACKENDS.md # Documentación backends mobile/web docs/research/WIDGET_COMPARISON.md # Comparativa zcatgui vs DVUI vs Gio @@ -77,6 +78,57 @@ Resumen breve (1-2 frases). Resultado principal. --- +## ⭐ TAREA PENDIENTE: Paridad Visual con DVUI + +> **Prioridad**: ALTA +> **Auditoría completa**: `docs/research/DVUI_AUDIT_2025-12-17.md` (570 líneas) +> **Consensuado**: 2025-12-17 + +### El Problema + +zcatgui tiene MÁS widgets que DVUI (~45 vs ~42), pero DVUI **se ve mejor** porque: +1. **Esquinas redondeadas** en todos los widgets +2. **Anti-aliasing en bordes** via edge-fade (no solo en TTF) +3. **Transiciones suaves** entre estados (hover, press) +4. **Sombras aplicadas** a paneles y modales + +### Solución Acordada + +Implementar sistema dual: `RenderMode.simple` (rápido) vs `RenderMode.fancy` (bonito) + +### Fases de Implementación + +**Fase 1: Rendering Visual (CRÍTICO)** +1. Crear `src/render/path.zig` - Paths con arcos para esquinas redondeadas +2. Modificar `software.zig` - AA en bordes via edge-fade technique +3. Actualizar widgets - corner_radius en Button, Panel, TextInput, Select, Modal + +**Fase 2: Estados Visuales** +4. Integrar AnimationManager en widgets para transiciones hover/press +5. Focus ring con anti-aliasing + +**Fase 3: Efectos** +6. Activar Shadow API existente (`effects.zig`) en Panel/Modal +7. Mejorar uso de gradientes + +**Estimación**: ~1,400 LOC nuevas/modificadas + +### Técnica Edge-Fade (de DVUI) + +``` +Cada borde tiene 2 vértices paralelos: +- Interno: color sólido (alpha = 1.0) +- Externo: transparente (alpha = 0.0) +GPU/CPU interpola → bordes suaves sin multisampling +``` + +### Documentación de Referencia + +- `docs/research/DVUI_AUDIT_2025-12-17.md` - Auditoría completa +- `docs/research/WIDGET_COMPARISON.md` - Comparativa anterior (actualizar después) + +--- + ## TAREA COMPLETADA: Fuentes TTF con Antialiasing ✅ ### Estado actual (v0.16.2) diff --git a/docs/research/DVUI_AUDIT_2025-12-17.md b/docs/research/DVUI_AUDIT_2025-12-17.md new file mode 100644 index 0000000..efec2a8 --- /dev/null +++ b/docs/research/DVUI_AUDIT_2025-12-17.md @@ -0,0 +1,504 @@ +# Auditoría Completa: DVUI vs zcatgui + +> **Fecha**: 2025-12-17 +> **Objetivo**: Identificar TODAS las características de DVUI que faltan en zcatgui +> **Versiones**: DVUI main (Dec 2025) | zcatgui v0.16.2 + +--- + +## 1. RESUMEN EJECUTIVO + +### Estado Actual + +| Aspecto | zcatgui | DVUI | Gap | +|---------|---------|------|-----| +| **Widgets** | ~45 | ~42 | ✅ Paridad | +| **Rendering Visual** | Básico | Avanzado | ❌ CRÍTICO | +| **Anti-aliasing** | Supersampling TTF | Edge-fade triangles | ⚠️ Diferente | +| **Esquinas redondeadas** | ❌ No | ✅ Sí | ❌ FALTA | +| **Sombras** | ✅ API existe | ✅ Box shadow | ⚠️ No usado | +| **Backends** | 4 (SDL2,WASM,Android,iOS) | 6 (SDL2/3,Raylib,DX11,Web) | ✅ OK | +| **Themes** | 5 | 6 | ✅ OK | + +### Conclusión Principal + +**El gap NO está en cantidad de widgets, sino en CALIDAD VISUAL del rendering.** + +DVUI se ve mejor porque: +1. Usa **triangulación con anti-aliasing en bordes** (fade to transparent) +2. Tiene **esquinas redondeadas nativas** en todos los widgets +3. Aplica **ninepatch** para efectos visuales complejos +4. **Estados visuales pulidos** (hover, press, focus) + +--- + +## 2. ANÁLISIS DEL SISTEMA DE RENDERING DE DVUI + +### 2.1 Arquitectura de Rendering + +DVUI usa un enfoque de **triangulación con vértices**: + +``` +Widget → Path (arcs, lines) → Triangles → GPU/CPU render +``` + +**Características clave:** +- Todos los elementos se convierten en triángulos +- Anti-aliasing via **2 vértices por borde**: inner (opaco) + outer (transparente) +- Tamaño de AA fijo: 1 pixel +- Soporte para GPU (DirectX, SDL3GPU) y CPU fallback + +### 2.2 Path Drawing + +```zig +// DVUI: Esquinas redondeadas con arcos +pub fn addRect(corner_radii) { + // 4 arcos (uno por esquina) + // 4 líneas conectando arcos + // Triangulación automática +} + +// Error de discretización configurable +theta = acos(radius / (radius + 0.5)); // 0.5px error máximo +``` + +### 2.3 Anti-Aliasing + +**DVUI usa "edge fade":** +- Cada borde tiene 2 vértices paralelos +- Vértice interno: color sólido (alpha = 1.0) +- Vértice externo: transparente (alpha = 0.0) +- Interpolación lineal entre ambos crea suavizado + +**Ventajas:** +- Funciona con GPU (hardware interpolation) +- Funciona con CPU (software interpolation) +- No requiere multisampling + +### 2.4 Fill Modes + +1. **Convex Fill**: Para polígonos convexos simples + - Triangulación desde centro + - Opcional: fade en bordes + +2. **Stroke Fill**: Para líneas y bordes + - Extrusión de geometría + - Miter joints con límite de ángulo + - AA fringe de 1px + +--- + +## 3. INVENTARIO COMPLETO DE WIDGETS + +### 3.1 DVUI Widgets (42 archivos) + +| Categoría | Widgets | +|-----------|---------| +| **Layout** | BoxWidget, FlexBoxWidget, GridWidget, PanedWidget, ScrollContainerWidget, OverlayWidget | +| **Input** | TextEntryWidget, ButtonWidget, DropdownWidget, ColorPickerWidget, ScaleWidget | +| **Display** | LabelWidget, IconWidget, PlotWidget, TextLayoutWidget | +| **Navigation** | MenuWidget, MenuItemWidget, TabsWidget, TreeWidget | +| **Floating** | FloatingWidget, FloatingWindowWidget, FloatingMenuWidget, FloatingTooltipWidget | +| **Utility** | AnimateWidget, CacheWidget, ContextWidget, FocusGroupWidget, ReorderWidget, ScrollAreaWidget, ScrollBarWidget, SuggestionWidget, VirtualParentWidget | + +### 3.2 zcatgui Widgets (~45 archivos) + +| Categoría | Widgets | +|-----------|---------| +| **Básicos** | label, button, checkbox, radio, slider, text_input, numberentry | +| **Layout** | panel, split, modal, scroll, tabs, menu, grid | +| **Datos** | list, table, tree, reorderable, virtual_scroll | +| **Feedback** | progress, tooltip, toast, loader | +| **Input Avanzado** | autocomplete, select, textarea, colorpicker, datepicker | +| **Especial** | image, icon, canvas, chart, richtext, breadcrumb, badge | +| **Navegación** | appbar, navdrawer, sheet, divider, discloser | +| **Extra** | switch, surface, resize, selectable, iconbutton, focus | + +### 3.3 Comparación Widget por Widget + +| Widget | zcatgui | DVUI | Notas | +|--------|:-------:|:----:|-------| +| Button | ✅ | ✅ | DVUI: esquinas redondeadas | +| Label | ✅ | ✅ | Similar | +| TextInput | ✅ | ✅ | DVUI: mejor touch | +| Checkbox | ✅ | ✅ | DVUI: animación | +| Radio | ✅ | ✅ | Similar | +| Slider | ✅ ScaleWidget | ✅ | Similar | +| Select/Dropdown | ✅ | ✅ | Similar | +| Panel/Box | ✅ | ✅ | Similar | +| Split/Paned | ✅ | ✅ | Similar | +| Tabs | ✅ | ✅ | Similar | +| ScrollArea | ✅ | ✅ | DVUI: smooth scroll | +| Modal | ✅ | ❌ FloatingWindow | Diferentes | +| Grid | ✅ | ✅ | Similar | +| Menu | ✅ | ✅ | Similar | +| Tree | ✅ | ✅ | Similar | +| Tooltip | ✅ | ✅ | Similar | +| Toast | ✅ | ❌ | zcatgui único | +| Progress | ✅ | ❌ | zcatgui único | +| ColorPicker | ✅ | ✅ | Similar | +| DatePicker | ✅ | ❌ | zcatgui único | +| Image | ✅ | ✅ | DVUI: stb_image | +| Icon | ✅ | ✅ TinyVG | DVUI: vectorial | +| Chart/Plot | ✅ | ✅ | Similar | +| Canvas | ✅ | ❌ | zcatgui único | +| VirtualScroll | ✅ | ✅ | Similar | +| Reorderable | ✅ | ✅ | Similar | +| AppBar | ✅ | ❌ | zcatgui único | +| NavDrawer | ✅ | ❌ | zcatgui único | +| Breadcrumb | ✅ | ❌ | zcatgui único | +| Badge | ✅ | ❌ | zcatgui único | +| RichText | ✅ | ✅ TextLayout | Similar | +| Loader/Spinner | ✅ | ❌ | zcatgui único | +| Switch | ✅ | ❌ | zcatgui único | +| Autocomplete | ✅ | ✅ Suggestion | Similar | +| Table editable | ✅⭐ | ❌ Grid básico | **zcatgui superior** | +| Floating Window | ❌ | ✅ | DVUI único | +| Animate | ❌ directo | ✅ | DVUI: widget dedicado | +| Cache | ❌ | ✅ | DVUI: optimización | + +**Conclusión Widgets**: zcatgui tiene MÁS widgets que DVUI, incluyendo varios únicos. + +--- + +## 4. DIFERENCIAS CRÍTICAS DE RENDERING + +### 4.1 Lo que DVUI hace mejor visualmente + +| Aspecto | DVUI | zcatgui | Impacto Visual | +|---------|------|---------|----------------| +| **Esquinas redondeadas** | ✅ corner_radius | ❌ Solo rectángulos | ⭐⭐⭐ ALTO | +| **Anti-aliasing bordes** | ✅ Edge fade | ❌ Solo en TTF | ⭐⭐⭐ ALTO | +| **Estados hover/press** | ✅ Transiciones suaves | ⚠️ Cambio abrupto | ⭐⭐ MEDIO | +| **Focus ring** | ✅ 2px stroke suave | ⚠️ Rectángulo | ⭐⭐ MEDIO | +| **Ninepatch** | ✅ Imágenes escalables | ❌ No | ⭐ BAJO | +| **Box shadow** | ✅ Blur real | ⚠️ API existe, no usada | ⭐⭐ MEDIO | + +### 4.2 Lo que zcatgui hace igual o mejor + +| Aspecto | zcatgui | DVUI | +|---------|---------|------| +| **TTF Rendering** | ✅ Supersampling 2x | ✅ stb_truetype | +| **Themes** | ✅ 5 themes | ✅ 6 themes | +| **Effects API** | ✅ Shadow, Gradient, Blur | ⚠️ Solo shadow | +| **Color utilities** | ✅ Básico | ✅ HSLuv completo | +| **Animation system** | ✅ 20+ easing functions | ✅ Similar | + +--- + +## 5. SISTEMA DE THEMING + +### 5.1 DVUI Themes + +```zig +// DVUI: Theme estructura +Theme { + // Colores por estilo + styles: [content, control, window, highlight, err, app1, app2, app3] + + // Cada estilo tiene: + fill, fill_hover, fill_press, + text, text_hover, text_press, + border, + ninepatch_fill, ninepatch_hover, ninepatch_press, + + // Fuentes + font_body, font_heading, font_title, font_mono, + + // Geometría + max_default_corner_radius, + + // Meta + dark: bool, + focus_color, + text_select_color, +} +``` + +### 5.2 Themes Disponibles + +| Theme | DVUI | zcatgui | +|-------|:----:|:-------:| +| Dark | ✅ | ✅ | +| Light | ✅ | ✅ | +| Adwaita | ✅ | ❌ | +| Dracula | ✅ | ✅ | +| Gruvbox | ✅ | ❌ | +| Jungle | ✅ | ❌ | +| OpenDyslexic | ✅ | ❌ | +| Win98 | ✅ | ❌ | +| Solarized | ❌ | ✅ | +| High Contrast | ❌ | ✅ | +| Nord | ❌ | ✅ | + +--- + +## 6. FEATURES ADICIONALES DE DVUI + +### 6.1 Features que NO tenemos + +| Feature | Descripción | Prioridad | +|---------|-------------|-----------| +| **structEntry** | Auto-genera UI desde struct Zig | MEDIA | +| **AccessKit** | Soporte screen readers | BAJA | +| **Fire-and-forget dialogs** | Dialogs desde cualquier punto | MEDIA | +| **HSLuv color space** | Manipulación perceptual de colores | BAJA | +| **TinyVG icons** | Iconos vectoriales compactos | MEDIA | +| **Ninepatch** | Imágenes escalables 9-slice | BAJA | +| **Cache Widget** | Cacheo de rendering costoso | MEDIA | +| **FPS throttling** | Control de framerate | BAJA | + +### 6.2 Features que YA tenemos equivalentes + +| Feature | DVUI | zcatgui | +|---------|------|---------| +| Macro system | ❌ | ✅ ÚNICO | +| Lego Panels | ❌ | ✅ ÚNICO | +| DataManager | ❌ | ✅ ÚNICO | +| Table editable | ❌ | ✅ SUPERIOR | +| Progress widgets | ❌ | ✅ | +| Toast notifications | ❌ | ✅ | +| DatePicker | ❌ | ✅ | +| Multiple progress styles | ❌ | ✅ | + +--- + +## 7. EASING Y ANIMACIONES + +### 7.1 DVUI Easing Functions + +- Linear +- Quad (in/out/inOut) +- Cubic (in/out/inOut) +- Quart (in/out/inOut) +- Quint (in/out/inOut) +- Sine +- Exponential +- Circular +- Elastic +- Back +- Bounce + +### 7.2 zcatgui Animation System + +Ya tenemos en `animation.zig`: +- 20+ easing functions (similar a DVUI) +- AnimationManager +- Spring physics +- lerp/lerpInt utilities + +**Conclusión**: Paridad en animaciones. + +--- + +## 8. BACKENDS + +### 8.1 Comparación + +| Backend | DVUI | zcatgui | +|---------|:----:|:-------:| +| SDL2 | ✅ | ✅ | +| SDL3 | ✅ | ❌ | +| SDL3GPU | ✅ | ❌ | +| Raylib | ✅ | ❌ | +| DirectX 11 | ✅ | ❌ | +| Web/Canvas | ✅ | ✅ WASM | +| Android | ❌ | ✅ | +| iOS | ❌ | ✅ | + +**Conclusión**: DVUI tiene más backends desktop, zcatgui tiene mobile. + +--- + +## 9. GAP ANALYSIS - QUÉ IMPLEMENTAR + +### 9.1 PRIORIDAD CRÍTICA (Mejora Visual Inmediata) + +| Mejora | Descripción | Esfuerzo | Impacto | +|--------|-------------|----------|---------| +| **Esquinas redondeadas** | corner_radius en todos los widgets | ALTO | ⭐⭐⭐ | +| **Anti-aliasing bordes** | Edge-fade en rectángulos/líneas | ALTO | ⭐⭐⭐ | +| **Aplicar sombras existentes** | Usar Shadow API en widgets | MEDIO | ⭐⭐ | +| **Hover/Press suave** | Transición gradual de colores | MEDIO | ⭐⭐ | + +### 9.2 PRIORIDAD ALTA (Mejora UX) + +| Mejora | Descripción | Esfuerzo | +|--------|-------------|----------| +| Focus ring suave | Borde con AA en lugar de rectángulo | +| Smooth scrolling | Animación al hacer scroll | +| Button states | Hover → Press → Release animados | +| Color transitions | Animación entre estados de color | + +### 9.3 PRIORIDAD MEDIA (Features) + +| Feature | Descripción | +|---------|-------------| +| structEntry | Auto UI desde structs | +| Cache widget | Para renders costosos | +| TinyVG icons | Iconos vectoriales | +| Más themes | Adwaita, Gruvbox, Win98 | + +### 9.4 PRIORIDAD BAJA (Nice to have) + +| Feature | Descripción | +|---------|-------------| +| AccessKit | Screen readers | +| HSLuv | Color perceptual | +| Ninepatch | 9-slice images | +| SDL3 backend | Nuevo SDL | + +--- + +## 10. PLAN DE IMPLEMENTACIÓN PROPUESTO + +### Fase 1: Rendering Visual (CRÍTICO) + +1. **Implementar Path con esquinas redondeadas** + - Crear `src/render/path.zig` + - Arcos discretizados + - addRoundedRect() + +2. **Anti-aliasing en bordes** + - Modificar `software.zig` + - Edge-fade technique + - Aplicar a drawRect, drawLine + +3. **Actualizar widgets existentes** + - Button: corner_radius + - Panel: corner_radius + - TextInput: corner_radius + - Select: corner_radius + - Modal: corner_radius + +### Fase 2: Estados Visuales + +4. **Transiciones de estado** + - Integrar AnimationManager en widgets + - Hover fade (200ms) + - Press transition (100ms) + +5. **Focus ring mejorado** + - Borde con AA + - Color de tema + +### Fase 3: Efectos + +6. **Aplicar sombras** + - Activar Shadow existente en Panel + - Activar en Modal + - Activar en Dropdown/Select + +7. **Mejorar gradientes** + - Usar en Progress bars + - Opcional en buttons + +### Fase 4: Features Adicionales + +8. **Widget variants** + - button_simple vs button_fancy + - panel_simple vs panel_fancy + +9. **Nuevos themes** + - Adwaita + - Gruvbox + +--- + +## 11. ARQUITECTURA PROPUESTA + +### 11.1 Sistema Dual: Simple vs Fancy + +```zig +// Configuración global +pub const RenderMode = enum { + simple, // Rápido, rectángulos, sin AA + fancy, // Esquinas redondeadas, AA, sombras +}; + +pub var render_mode: RenderMode = .fancy; + +// En cada widget +pub fn button(ctx, text) { + if (render_mode == .fancy) { + drawRoundedRect(corner_radius: 5); + applyShadow(); + } else { + drawRect(); + } +} +``` + +### 11.2 Nuevos Módulos Necesarios + +``` +src/render/ +├── path.zig # NUEVO: Path con arcos y curvas +├── triangulate.zig # NUEVO: Triangulación de paths +├── software.zig # MODIFICAR: AA en primitivas +├── effects.zig # YA EXISTE: Activar en widgets +├── antialiasing.zig # YA EXISTE: Extender +``` + +--- + +## 12. MÉTRICAS DE ÉXITO + +### Antes vs Después + +| Aspecto | Antes | Después | +|---------|-------|---------| +| Esquinas | Rectangulares | Redondeadas configurable | +| Bordes | Aliased | Anti-aliased | +| Sombras | No usadas | En paneles/modales | +| Transiciones | Abruptas | Suaves (200ms) | +| Focus | Rectángulo | Ring con AA | + +### Comparación Visual Objetivo + +``` +ANTES (zcatgui actual): +┌────────────────┐ +│ Botón │ ← Esquinas 90° +└────────────────┘ Sin sombra + Cambio abrupto hover + +DESPUÉS (estilo DVUI): +╭────────────────╮ +│ Botón │ ← Esquinas redondeadas +╰────────────────╯ Sombra sutil + Transición suave hover +``` + +--- + +## 13. CONCLUSIONES + +### Lo que DVUI hace mejor +1. **Rendering visual** - Esquinas redondeadas, AA en todo +2. **Estados de widgets** - Transiciones suaves +3. **Consistencia visual** - Todo se ve "pulido" + +### Lo que zcatgui hace mejor +1. **Sistema de macros** - Único +2. **Table widget** - Más completo (edit, sort, validate) +3. **Lego Panels** - Arquitectura de composición +4. **Más widgets** - Progress, DatePicker, Toast, etc. +5. **Mobile backends** - Android, iOS + +### Recomendación Final + +**NO necesitamos reescribir zcatgui.** Necesitamos: + +1. **Añadir esquinas redondeadas** (~500 LOC nuevo código) +2. **Mejorar anti-aliasing** (~300 LOC modificaciones) +3. **Aplicar efectos existentes** (~200 LOC en widgets) +4. **Añadir transiciones** (~400 LOC) + +**Total estimado: ~1,400 LOC para alcanzar paridad visual con DVUI.** + +El esfuerzo es significativamente menor que reescribir desde cero, y mantiene nuestras ventajas únicas (macros, table, panels). + +--- + +*Auditoría completada 2025-12-17*