# DevExpress grid e Tesi Platform

## Indice

1. Confine con il grid debugger
2. DevExpress grid performance
3. TesiGrid structural lifecycle
4. Selection e detail
5. SuperPlanning widgets
6. Regole di scope

## 1. Confine con il grid debugger

Usa `mcp-grid-ui-debugger` quando il sintomo primario è larghezza errata, flicker, scrollbar, footer o drag geometrico. Usa questa reference quando il sintomo include main-thread stall, render/interop ripetuto, DOM churn, leak o lentezza sistemica della pagina.

Le API e le classi private DevExpress cambiano tra versioni. Preferisci ARIA, wrapper applicativi, bounding rect e API pubbliche. Tratta `DXGrid` e selettori interni come fallback version-specific, non come contratto stabile.

## 2. DevExpress grid performance

Controlla:

- `ShowAllRows` versus virtual scrolling e grouping;
- numero di colonne renderizzate, incluse colonne hidden;
- detail template annidati e lifecycle delle sub-grid;
- summary e selected-summary;
- selection column e callback per riga;
- misure ripetute di header/celle;
- refresh/reload invocati durante render o resize.

Non attivare virtualizzazione o server grouping senza verificare correttezza di grouping, summary, detail, drag e scrolling. Un dataset piccolo non giustifica un refactor backend per large-grid.

## 3. TesiGrid structural lifecycle

Per il wrapper TesiGrid:

- mantieni un solo controller DOM per container;
- invalida readiness tramite generation;
- coalesci mutation/resize/update per frame;
- esegui letture prima delle scritture;
- misura header e una riga rappresentativa;
- ignora callback di generation obsolete;
- possiedi observer, RAF e timer e disponili con il componente;
- evita full structural pass durante scroll stabile;
- usa un safety cap finito e registra il fallback.

Non mantenere un controller legacy e uno sperimentale se la parità di Orders/Trips non è dimostrata. Rimuovi l'esperimento quando il costo di manutenzione supera il beneficio misurato.

## 4. Selection e detail

Per selection ad alta frequenza:

- evita render completo della grid per il solo check visuale;
- mantieni una sorgente di verità managed;
- sincronizza DOM e callback con version;
- testa checkbox singola, sequenza, select-all, grouping e summary selezionati;
- verifica che lo stato torni al baseline dopo deselect.

Per detail nested:

- carica con generation/cancellation;
- mostra pending state esplicito;
- non lanciare fetch dal render path;
- memorizza empty/error per la generation quando serve evitare retry loop;
- testa livello vuoto, errore, open/close ripetuto e navigation durante load.

## 5. SuperPlanning widgets

Verifica insieme:

- Orders (`SegmentWidget`) e nested level 2/3;
- Trips (`TripWidget`) e nested segment grid;
- Map selection e drag;
- FleetCalendar refresh, carrier options e drag;
- GridStack resize/move/lock;
- cross-tab bus e listener di drag;
- configurazioni batch e lookup location.

Per Map/FleetCalendar/cross-tab, lega listener globali alla sola interazione quando possibile e rimuovili su release, drag-end, error e disposal.

## 6. Regole di scope

Applica il fix nel layer proprietario corretto:

- TesiGrid Core: tutte le istanze che usano quel comportamento;
- parametro opt-in TesiGrid: tutte le istanze del componente che lo abilitano;
- SegmentWidget/TripWidget/Map/FleetCalendar: tutte le istanze del widget;
- PlanningManagement: tutte le pagine Planning compatibili;
- query `tesiPerf=1`: sola diagnostica esplicita.

Non aggiungere condizioni per group ID, scenario ID, URL di benchmark, tenant o singolo widget runtime. Usa tali valori solo nella configurazione test/documentazione.

Prima del merge verifica le regole Platform in `.cursor/rules`, la documentazione `_documentation/`, `node --check`, `git diff --check`, i test TUnit pertinenti e uno smoke nel browser compilato dall'owner.