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

// 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

// 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)

// 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)

// 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

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

// 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