zcatgui/docs/research/SIMIFACTU_ADVANCEDTABLE.md

# Analisis AdvancedTable de Simifactu

> Fecha: 2025-12-09
> Proposito: Extraer features de AdvancedTable para mejorar Table de zcatgui

---

## Resumen

AdvancedTable es un componente de ~10,000 LOC en Go/Fyne que proporciona una experiencia tipo Excel para edicion de tablas. Es el componente mas complejo de Simifactu.

**Ubicacion**: `/mnt/cello2/arno/re/recode/go/simifactu-fyne/internal/ui/components/advanced_table/`

---

## 1. Features Actuales de zcatgui Table

| Feature | Estado | Descripcion |
|---------|--------|-------------|
| Renderizado | OK | Columnas, filas, scrolling |
| Seleccion | OK | Click y teclado |
| Edicion in-situ | OK | F2/Enter para editar |
| Dirty tracking | OK | newRows, modifiedRows |
| Navegacion teclado | OK | Flechas, Tab, Home/End |
| Colores por estado | OK | Normal, selected, modified, new |

---

## 2. Features de AdvancedTable que FALTAN en zcatgui

### 2.1 CRITICO (Necesario para MVP)

| Feature | Prioridad | Descripcion |
|---------|-----------|-------------|
| **Column Sorting** | CRITICA | Click en header para ordenar asc/desc |
| **Column Resize** | CRITICA | Arrastrar borde de header para redimensionar |
| **Row Operations** | CRITICA | Ctrl+N (insert), Ctrl+A (append), Ctrl+Del (delete) |
| **Auto-CRUD** | ALTA | Detectar cambios y auto-save al cambiar de fila |
| **Validation** | ALTA | Validacion por celda con errores visuales |

### 2.2 IMPORTANTE (Necesario para Simifactu-GUI)

| Feature | Prioridad | Descripcion |
|---------|-----------|-------------|
| **Calculated Columns** | ALTA | Columnas calculadas (Total = Cantidad * Precio) |
| **Row Locking** | ALTA | Filas de solo lectura (facturas certificadas) |
| **Lookup Fields** | ALTA | Busqueda en tabla relacionada + auto-fill |
| **Cross-Column Validation** | MEDIA | Validar combinaciones (IVA + RE compatibles) |
| **State Column** | MEDIA | Columna con iconos de estado (semaforo) |

### 2.3 NICE TO HAVE

| Feature | Prioridad | Descripcion |
|---------|-----------|-------------|
| **Row Types** | BAJA | Diferentes comportamientos por tipo de fila |
| **Debounced Callbacks** | MEDIA | Evitar flood de eventos durante navegacion rapida |
| **Spanish Collation** | BAJA | Ordenar con acentos correctamente |
| **Color Cache** | MEDIA | Optimizacion de colores pre-calculados |

---

## 3. Detalle de Features Criticas

### 3.1 Column Sorting

```
Implementacion en Simifactu:
- Click en header → toggle asc/desc/none
- Icono visual en header (▲/▼/-)
- Mantener originalRowsForSort para dirty tracking
- Spanish collation optional
```

**Para zcatgui:**
```zig
pub const TableConfig = struct {
    // ... existing
    allow_sorting: bool = false,
};

pub const TableState = struct {
    // ... existing
    sort_column: i32 = -1,  // -1 = no sort
    sort_asc: bool = true,
};

pub const TableResult = struct {
    // ... existing
    sort_changed: bool = false,
    sort_column: ?usize = null,
};
```

### 3.2 Column Resize

```
Implementacion en Simifactu:
- Fyne no lo soporta nativamente
- Workaround: arrastrar divisores
```

**Para zcatgui:**
- Detectar hover en borde de header
- Cursor cambia a resize
- Drag actualiza column.width

### 3.3 Row Operations (Keyboard Shortcuts)

```
Simifactu shortcuts:
- Ctrl+N → Insert row BEFORE current
- Ctrl+A → Append row AFTER current
- Ctrl+B / Del → Delete current row (mark for deletion)
- Ctrl+Up → Move row up
- Ctrl+Down → Move row down
```

**Para zcatgui:**
```zig
pub const TableResult = struct {
    // ... existing
    row_inserted: bool = false,
    row_deleted: bool = false,
    row_moved: bool = false,
    insert_position: ?usize = null,
};
```

### 3.4 Auto-CRUD Detection

```
Simifactu implementation:
1. Al ENTRAR en fila → guardar snapshot
2. Al SALIR de fila → comparar con snapshot
3. Si cambio → detectar CREATE/UPDATE/DELETE
4. Trigger OnRowSave callback
```

**Para zcatgui:**
- Ya tenemos dirtyRows
- Falta: snapshot al entrar en fila
- Falta: callback on_row_exit

### 3.5 Validation

```
Simifactu types:
- ValueValidator: single cell validation
- CrossColumnValidator: multi-cell validation
- ValidationResult: {valid, errorMessage}
- Visual: error rows get red background
```

**Para zcatgui:**
```zig
pub const ColumnValidation = struct {
    validator: ?*const fn(value: []const u8) ?[]const u8, // null = valid, else error
};

pub const TableState = struct {
    // ... existing
    validation_errors: [MAX_ROWS]bool = .{false} ** MAX_ROWS,
};
```

---

## 4. Arquitectura de AdvancedTable

### 4.1 Archivos y Responsabilidades

| Archivo | LOC | Responsabilidad |
|---------|-----|-----------------|
| types.go | 600 | Tipos y schemas |
| core.go | 1200 | Constructor, build, routing |
| editing.go | 700 | Edicion in-situ, Entry overlay |
| navigation.go | 500 | Navegacion teclado |
| row_operations.go | 600 | CRUD de filas |
| sorting.go | 400 | Ordenacion |
| validation.go | 500 | Validacion |
| calculated.go | 400 | Columnas calculadas |
| visual.go | 700 | Colores, estados visuales |
| datastore.go | 600 | Persistencia abstraccion |
| lookup.go | 350 | Campos lookup |
| callbacks.go | 400 | Gestion callbacks |
| autocrud.go | 400 | Auto CRUD detection |

### 4.2 Patron de Callbacks

```go
// Schema-level callbacks (globales)
OnRowSelected  func(rowIndex int, rowData map[string]interface{})
OnCellEdited   func(rowIndex, colIndex int, oldValue, newValue interface{}) error
OnSave         func(rowData map[string]interface{}) error
OnDelete       func(rowData map[string]interface{}) error
OnValidate     func(rowIndex, colIndex int, value interface{}) error

// Column-level callbacks (por columna)
ColumnDef.OnGetFocus     func(rowIndex int, value interface{})
ColumnDef.OnLoseFocus    func(rowIndex int, value interface{}) error
ColumnDef.OnValueChanged func(rowIndex int, oldValue, newValue interface{})
```

---

## 5. Plan de Implementacion para zcatgui

### Fase 1: Sorting (Estimacion: 2-3 horas)
1. Agregar sort_column/sort_asc a TableState
2. Detectar click en header
3. Reordenar indices (no mover datos)
4. Dibujar icono en header

### Fase 2: Row Operations (Estimacion: 2-3 horas)
1. Detectar Ctrl+N/A/B
2. Insertar/eliminar filas en data
3. Actualizar indices dirty/new
4. Reportar en TableResult

### Fase 3: Validation (Estimacion: 2-3 horas)
1. Agregar validator a Column
2. Llamar validator en cell edit commit
3. Guardar errores en state
4. Renderizar filas con error diferente

### Fase 4: Calculated Columns (Estimacion: 3-4 horas)
1. Agregar calculate_fn a Column
2. Detectar dependencias
3. Recalcular al cambiar dependencia
4. Renderizar como read-only

### Fase 5: Auto-CRUD (Estimacion: 2-3 horas)
1. Guardar snapshot al entrar en fila
2. Comparar al salir
3. Trigger callback si cambio

### Fase 6: Column Resize (Estimacion: 3-4 horas)
1. Detectar hover en borde
2. Cambiar cursor
3. Drag para resize
4. Guardar nuevo width

**Total estimado: 15-20 horas**

---

## 6. Prioridades para zcatgui Table v2

### Must Have (MVP)
- [ ] Column sorting
- [ ] Row insert/delete
- [ ] Basic validation

### Should Have (v0.7)
- [ ] Calculated columns
- [ ] Auto-CRUD callbacks
- [ ] Row locking

### Nice to Have (v0.8+)
- [ ] Column resize
- [ ] Cross-column validation
- [ ] Lookup fields
- [ ] Debounced callbacks

---

## 7. Conclusion

AdvancedTable de Simifactu es un componente muy maduro con features enterprise. Para zcatgui, debemos:

1. **Fase inmediata**: Sorting + Row operations (features mas usadas)
2. **Fase siguiente**: Validation + Calculated columns
3. **Fase posterior**: Auto-CRUD + Column resize

El approach de schema-driven de Simifactu es bueno pero requiere mas LOC. Para zcatgui, mantener API simple y agregar features incrementalmente.