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:

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:

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:

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

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