diff --git a/docs/ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md b/docs/ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md new file mode 100644 index 0000000..510c731 --- /dev/null +++ b/docs/ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md @@ -0,0 +1,473 @@ +# AdvancedTable - Análisis de Mejoras Potenciales + +> **Fecha:** 2025-12-17 +> **Estado:** ANÁLISIS para consensuar +> **Objetivo:** Identificar funcionalidades a incorporar de otros widgets + investigación web + +--- + +## Resumen Ejecutivo + +AdvancedTable tiene **8 fases completas** (~2,700 LOC), pero hay funcionalidades en otros widgets de zcatgui que podrían incorporarse, además de features estándar de tablas modernas que no tenemos. + +--- + +## Funcionalidades YA en otros widgets de zcatgui + +### 1. Multi-Row Selection (de `table/state.zig`) + +**Estado:** NO está en AdvancedTable + +```zig +// En table/state.zig existe: +selected_rows: [128]u8 = [_]u8{0} ** 128, // Bit array (1024 rows) +selection_anchor: i32 = -1, // Para Shift+click + +pub fn isRowSelected(row) bool +pub fn addRowToSelection(row) void +pub fn removeRowFromSelection(row) void +pub fn toggleRowSelection(row) void +pub fn selectAllRows() void // Ctrl+A +pub fn selectRowRange(from, to) void // Shift+click +pub fn getSelectedRowCount() usize +pub fn getSelectedRows(buffer) usize +``` + +**Uso:** Operaciones masivas (borrar múltiples, exportar selección, etc.) + +**LOC estimadas:** ~80 + +--- + +### 2. Incremental Search / Type-to-Search (de `table/state.zig`) + +**Estado:** NO está en AdvancedTable + +```zig +// En table/state.zig existe: +search_buffer: [64]u8, +search_len: usize, +search_last_time: u64, +search_timeout_ms: u64 = 1000, // Reset después de 1s sin teclear + +pub fn addSearchChar(char, current_time) []const u8 +pub fn getSearchTerm() []const u8 +pub fn clearSearch() void + +// En keyboard.zig: +pub fn startsWithIgnoreCase(haystack, needle) bool +``` + +**Uso:** Escribir "gar" salta a primera fila que empieza con "Gar..." (como en listas de SO) + +**LOC estimadas:** ~60 + +--- + +### 3. Cell Validation con Error Tracking (de `table/state.zig`) + +**Estado:** PARCIAL en AdvancedTable (tenemos RowState.error pero no tracking detallado) + +```zig +// En table/state.zig existe: +validation_errors: [256]u32, // Cell IDs con error +validation_error_count: usize, +last_validation_message: [128]u8, + +pub fn hasCellError(row, col) bool +pub fn addCellError(row, col, message) void +pub fn clearCellError(row, col) void +pub fn clearAllErrors() void +pub fn hasAnyErrors() bool +pub fn getLastValidationMessage() []const u8 + +// Callback: +pub const CellValidateFn = fn(row, col, value) ValidationResult; +pub const ValidationResult = struct { valid: bool, message: []const u8 }; +``` + +**Uso:** Validar NIF/CIF, emails, rangos numéricos, campos requeridos + +**LOC estimadas:** ~100 + +--- + +### 4. Variable Row Heights (de `virtual_scroll.zig`) + +**Estado:** NO está en AdvancedTable (altura fija por config) + +```zig +// En virtual_scroll.zig existe: +item_heights: [10000]u16, // Altura por ítem +default_height: u16 = 24, + +pub fn setItemHeight(index, height) void +pub fn getItemHeight(index) u16 +pub fn recalculateTotalHeight() void +pub fn scrollToItem(index, viewport_height) void +``` + +**Uso:** Celdas con texto multilínea, filas expandidas con detalles + +**LOC estimadas:** ~50 + +--- + +### 5. Horizontal Scroll (de `table/state.zig`) + +**Estado:** NO está en AdvancedTable + +```zig +scroll_x: i32 = 0, // Existe en table/state.zig pero no se usa mucho +``` + +**Uso:** Tablas con muchas columnas que no caben en pantalla + +**LOC estimadas:** ~40 + +--- + +### 6. Double-Click Detection (de `grid.zig`) + +**Estado:** NO está en AdvancedTable + +```zig +// En grid.zig Result: +double_clicked: ?usize, // Marcado como TODO pero estructura existe +``` + +**Uso:** Doble-click para editar, abrir detalle, expandir fila + +**LOC estimadas:** ~30 + +--- + +## Funcionalidades de Tablas Modernas (investigación web) + +Basado en librerías como AG Grid, TanStack Table, Handsontable, MUI DataGrid: + +### 7. Frozen Columns (Pin) + +**Estado:** NO existe en zcatgui + +**Descripción:** Fijar columnas a izquierda/derecha que no se mueven al hacer scroll horizontal + +**Uso:** Mantener visible ID o nombre mientras se scrollean otras columnas + +**Complejidad:** ALTA - requiere renderizado en dos pasadas + +**LOC estimadas:** ~150 + +--- + +### 8. Column Resizing (Drag) + +**Estado:** NO existe en zcatgui + +**Descripción:** Arrastrar borde de columna para redimensionar + +**Uso:** Ajustar anchos según contenido + +**Complejidad:** MEDIA - detectar drag en borde, actualizar width + +**LOC estimadas:** ~80 + +--- + +### 9. Column Reordering (Drag & Drop) + +**Estado:** NO existe en zcatgui + +**Descripción:** Arrastrar header para reordenar columnas + +**Uso:** Personalizar vista de tabla + +**Complejidad:** ALTA - requiere array de índices de orden + +**LOC estimadas:** ~100 + +--- + +### 10. Copy/Paste (Clipboard) + +**Estado:** PARCIAL - tenemos `clipboard.zig` pero no integrado en table + +**Descripción:** +- Ctrl+C: Copiar celda(s) seleccionada(s) +- Ctrl+V: Pegar en celda(s) +- Copiar rango → pegar en Excel + +**Uso:** Interoperabilidad con Excel/Sheets + +**Complejidad:** MEDIA - ya tenemos clipboard system + +**LOC estimadas:** ~60 + +--- + +### 11. Multi-Column Sorting + +**Estado:** PARCIAL - tenemos sorting pero solo 1 columna + +**Descripción:** Shift+click en headers para ordenar por múltiples columnas + +**Uso:** "Ordenar por Provincia, luego por Población" + +**Complejidad:** BAJA - array de (columna, dirección) + +**LOC estimadas:** ~40 + +--- + +### 12. Column Filtering (Per-Column) + +**Estado:** NO existe en zcatgui + +**Descripción:** Dropdown/input en cada header para filtrar + +**Uso:** Mostrar solo filas donde "Provincia = Barcelona" + +**Complejidad:** ALTA - requiere UI en header + lógica filtrado + +**LOC estimadas:** ~200 + +--- + +### 13. Export (CSV/Excel) + +**Estado:** NO existe en zcatgui + +**Descripción:** Exportar tabla a archivo + +**Uso:** Generar informes, backup de datos + +**Complejidad:** BAJA (CSV) / MEDIA (Excel) + +**LOC estimadas:** ~80 (CSV), ~200 (Excel) + +--- + +### 14. Row Grouping + +**Estado:** NO existe en zcatgui + +**Descripción:** Agrupar filas por valor de columna (como pivot) + +**Uso:** "Agrupar facturas por cliente" + +**Complejidad:** MUY ALTA - reestructuración completa de datos + +**LOC estimadas:** ~300+ + +--- + +### 15. State Persistence + +**Estado:** NO existe en zcatgui + +**Descripción:** Guardar/restaurar preferencias (anchos, orden, filtros) + +**Uso:** Mantener configuración del usuario entre sesiones + +**Complejidad:** BAJA - serializar estado a JSON/config + +**LOC estimadas:** ~60 + +--- + +## Matriz de Priorización + +| # | Feature | Existe en zcatgui | Uso en zsimifactu | LOC | Prioridad | +|---|---------|-------------------|-------------------|-----|-----------| +| 1 | Multi-row selection | ✅ table/ | ALTA (borrar múltiples) | ~80 | **ALTA** | +| 2 | Incremental search | ✅ table/ | MEDIA (buscar rápido) | ~60 | **ALTA** | +| 3 | Cell validation | ✅ table/ | ALTA (NIF, email) | ~100 | **ALTA** | +| 10 | Copy/Paste | ✅ clipboard.zig | MEDIA (interop Excel) | ~60 | **MEDIA** | +| 11 | Multi-column sort | Parcial | BAJA | ~40 | **MEDIA** | +| 6 | Double-click | ✅ grid.zig | MEDIA (editar rápido) | ~30 | **MEDIA** | +| 8 | Column resizing | ❌ | MEDIA | ~80 | **MEDIA** | +| 5 | Horizontal scroll | ✅ table/ | BAJA (pocas cols) | ~40 | **BAJA** | +| 4 | Variable row heights | ✅ virtual_scroll | BAJA | ~50 | **BAJA** | +| 15 | State persistence | ❌ | BAJA | ~60 | **BAJA** | +| 13 | Export CSV | ❌ | MEDIA | ~80 | **BAJA** | +| 7 | Frozen columns | ❌ | BAJA | ~150 | **BAJA** | +| 9 | Column reordering | ❌ | BAJA | ~100 | **BAJA** | +| 12 | Column filtering | ❌ | MEDIA | ~200 | **FUTURA** | +| 14 | Row grouping | ❌ | BAJA | ~300+ | **FUTURA** | + +--- + +## Propuesta: Fases 9-11 de AdvancedTable + +### Fase 9: Selection & Search (~140 LOC) +- Multi-row selection (Ctrl+click, Shift+click, Ctrl+A) +- Incremental search (type-to-search con timeout) + +### Fase 10: Validation & Clipboard (~160 LOC) +- Cell validation con error tracking visual +- Copy/Paste integración (Ctrl+C/V) + +### Fase 11: UX Polish (~150 LOC) +- Double-click para editar +- Multi-column sorting +- Column resizing (drag header border) + +**Total estimado:** ~450 LOC adicionales + +--- + +## Decisión: ESPERAR VALIDACIÓN + +**Consensuado 2025-12-17:** Esperar a probar AdvancedTable en zsimifactu antes de implementar más fases. + +--- + +## Tareas Pendientes (Post-Validación) + +### Prioridad ALTA (reutilización de código existente) + +- [ ] **TASK-AT-9a**: Multi-row selection + - Copiar de `table/state.zig`: bit array, selection_anchor + - Funciones: isRowSelected, addRowToSelection, selectRowRange, selectAllRows + - Ctrl+click toggle, Shift+click range, Ctrl+A select all + - ~80 LOC + +- [ ] **TASK-AT-9b**: Incremental search (type-to-search) + - Copiar de `table/state.zig`: search_buffer, timeout 1s + - Copiar de `table/keyboard.zig`: startsWithIgnoreCase + - Saltar a primera fila que matchea + - ~60 LOC + +- [ ] **TASK-AT-10a**: Cell validation con error tracking + - Copiar de `table/state.zig`: validation_errors array, hasCellError, addCellError + - CellValidateFn callback + - Visual: borde rojo en celdas con error + - ~100 LOC + +- [ ] **TASK-AT-10b**: Copy/Paste integración + - Usar `clipboard.zig` existente + - Ctrl+C: copiar celda(s) seleccionada(s) + - Ctrl+V: pegar en celda actual + - Formato texto plano (compatible Excel) + - ~60 LOC + +### Prioridad MEDIA (nueva funcionalidad) + +- [ ] **TASK-AT-11a**: Double-click para editar + - Detectar doble-click en celda + - Alternativa a F2/Enter + - ~30 LOC + +- [ ] **TASK-AT-11b**: Multi-column sorting + - Shift+click en header para añadir columna al sort + - Array de (columna, dirección) + - Indicador visual "1^", "2v" + - ~40 LOC + +- [ ] **TASK-AT-11c**: Column resizing (drag) + - Detectar drag en borde derecho de header + - Cursor resize al hover + - Actualizar column.width + - ~80 LOC + +### Prioridad BAJA (nice-to-have) + +- [ ] **TASK-AT-12a**: Horizontal scroll + - scroll_x en state + - Scrollbar horizontal + - ~40 LOC + +- [ ] **TASK-AT-12b**: Variable row heights + - Array de alturas por fila + - Útil para celdas multilínea + - ~50 LOC + +- [ ] **TASK-AT-12c**: Export CSV + - Generar CSV de datos visibles + - Respetar filtros/orden actual + - ~80 LOC + +### Prioridad FUTURA (considerar si hay demanda) + +- [ ] **TASK-AT-F1**: Frozen columns (pin) +- [ ] **TASK-AT-F2**: Column reordering (drag & drop) +- [ ] **TASK-AT-F3**: Column filtering (per-column dropdowns) +- [ ] **TASK-AT-F4**: Row grouping +- [ ] **TASK-AT-F5**: State persistence (guardar preferencias) + +--- + +## Consideración: Merge Table + AdvancedTable + +### Situación Actual + +Tenemos **dos widgets de tabla** en zcatgui: + +| Aspecto | `table/` (original) | `advanced_table/` (nuevo) | +|---------|---------------------|---------------------------| +| **LOC** | ~800 | ~2,700 | +| **Archivos** | 5 (table, types, state, render, keyboard) | 4 (types, schema, state, advanced_table) | +| **Paradigma** | Callbacks (getCellData, onEdit) | Schema-driven (Row objects) | +| **Datos** | Externos (caller provee) | Internos (state.rows ArrayList) | +| **Multi-select** | ✅ Sí | ❌ No | +| **Search** | ✅ Sí | ❌ No | +| **Validation** | ✅ Tracking detallado | ❌ Solo RowState.error | +| **Lookup** | ❌ No | ✅ Sí (DataStore) | +| **Auto-CRUD** | ❌ No | ✅ Sí | +| **Callbacks** | onEdit simple | Jerárquicos + debounce | + +### Opciones de Merge + +#### Opción A: AdvancedTable absorbe Table +- Añadir features de Table a AdvancedTable +- Deprecar Table original +- **Pro:** Un solo widget completo +- **Con:** AdvancedTable crece mucho (~3,500 LOC) + +#### Opción B: Table absorbe AdvancedTable +- Añadir schema/CRUD a Table original +- Mantener paradigma de callbacks +- **Pro:** Código más compacto +- **Con:** Requiere reescribir bastante + +#### Opción C: Mantener ambos (actual) +- Table para casos simples (callbacks) +- AdvancedTable para casos complejos (CRUD, lookup) +- **Pro:** Flexibilidad, no rompe código existente +- **Con:** Duplicación de lógica + +#### Opción D: Crear TableCore compartido +- Extraer lógica común a módulo base +- Table y AdvancedTable heredan/componen +- **Pro:** DRY, mejor arquitectura +- **Con:** Refactoring significativo + +### Recomendación + +**Esperar a validar AdvancedTable en uso real.** Después: + +1. Si AdvancedTable funciona bien → **Opción A** (absorber Table) +2. Si hay problemas con schema-driven → **Opción C** (mantener ambos) +3. Si el código crece demasiado → **Opción D** (extraer TableCore) + +--- + +## Timeline Propuesto + +``` +[Ahora] Validar AdvancedTable fases 1-8 en zsimifactu + ↓ +[+1 semana] Evaluar resultado, decidir merge + ↓ +[+2 semanas] Implementar fases 9-10 (multi-select, validation) + ↓ +[+3 semanas] Implementar fase 11 (UX polish) + ↓ +[Futuro] Evaluar features de prioridad FUTURA +``` + +--- + +*Análisis por: Claude Code (Opus 4.5)* +*Fecha: 2025-12-17* +*Estado: PENDIENTE VALIDACIÓN*