zcatgui/docs/ADVANCED_TABLE_ENHANCEMENT_ANALYSIS.md

# 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*