docs: Análisis mejoras AdvancedTable + consideración merge
Documento ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md: - Features de table/ que faltan en AdvancedTable - Features de virtual_scroll y grid aplicables - Investigación web: features estándar de tablas modernas - Tareas priorizadas (TASK-AT-9 a TASK-AT-F5) - Análisis merge Table + AdvancedTable (4 opciones) - Timeline propuesto post-validación Decisión: ESPERAR validación en zsimifactu antes de implementar 🤖 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
964523b883
commit
3aac03da4a
1 changed files with 473 additions and 0 deletions
473
docs/ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md
Normal file
473
docs/ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md
Normal file
|
|
@ -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*
|
||||
Loading…
Reference in a new issue