@topconsultnpm/sdkui-react 6.22.0-t1 → 6.22.0-t3

package/lib/hooks/useMultiMasterDetailDcmts.js

@@ -0,0 +1,758 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { AccessLevels, ArchiveConstraints, ArchiveEngineByID, DcmtOpers, GeneralRetrieveFormats, MetadataDataDomains, MetadataDataTypes, RelationCacheService, RelationTypes, ResultTypes, RetrieveFileOptions, SDK_Globals, SystemMIDsAsNumber } from '@topconsultnpm/sdk-ts';
+import { MetadataValueDescriptorEx } from '../ts';
+import { clearMultiDetailLayout, Globalization, getExceptionMessage, getMultiDetailSectionsOpen, handleArchiveVisibility, hasMultiDetailLayout, saveMultiDetailSectionsOpen, SDKUI_Localizator } from '../helper';
+import { canViewMetadata, getDcmtMetadataByMid, getUserMetadataSorted, mapAssociationsFromMetadata } from '../helper/dcmtsHelper';
+import { ButtonNames, TMExceptionBoxManager, TMMessageBoxManager } from '../components/base/TMPopUp';
+import TMSpinner from '../components/base/TMSpinner';
+import { TMWaitPanelManager } from '../components/base/waitPanel';
+import ShowAlert from '../components/base/TMAlert';
+import { TMResultManager } from '../components/forms/TMResultDialog';
+import { useDataListItem } from './useDataListItem';
+import { buildColumnsFromDtd, canArchive, canUpdateMasterCallback, getDetailDtdAsync, toArchiveRowValue, toGridNumber } from '../components/features/documents/TMMultiMasterDetailDcmtsUtils';
+/** Fasi del flusso di archiviazione multipla dei dettagli */
+export var MultiDetailArchivePhase;
+(function (MultiDetailArchivePhase) {
+    /** Scelta del tipo documento */
+    MultiDetailArchivePhase[MultiDetailArchivePhase["SelectDcmtType"] = 0] = "SelectDcmtType";
+    /** Riepilogo delle archiviazioni */
+    MultiDetailArchivePhase[MultiDetailArchivePhase["ArchiveSummary"] = 1] = "ArchiveSummary";
+})(MultiDetailArchivePhase || (MultiDetailArchivePhase = {}));
+/**
+ * Logica dell'archiviazione multipla dei dettagli: relazioni, sezioni, righe del riepilogo e
+ * archiviazione. Il rendering sta in TMMultiMasterDetailDcmtsForm
+ */
+export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose, canNavigateMaster, onNavigateMaster }) => {
+    const { renderDataListCell, loadDataListsAsync } = useDataListItem();
+    const [isLoading, setIsLoading] = useState(true);
+    const [phase, setPhase] = useState(MultiDetailArchivePhase.SelectDcmtType);
+    const [detailRelationItems, setDetailRelationItems] = useState([]);
+    const [selectedRelation, setSelectedRelation] = useState(undefined);
+    // Il mount della griglia è differito di un frame, così stepper e titolo si dipingono subito
+    const [isSummaryReady, setIsSummaryReady] = useState(false);
+    // Struttura del tipo documento selezionato
+    const [detailColumns, setDetailColumns] = useState([]);
+    const [detailSupportsFile, setDetailSupportsFile] = useState(false);
+    // Mid numerici del tipo di dettaglio: in griglia le loro celle portano il numero (vedi buildArchiveRow)
+    const numericMidsRef = useRef(new Set());
+    // Dettagli già archiviati del tipo selezionato, collegati al master
+    const [archivedDetailResults, setArchivedDetailResults] = useState([]);
+    const [isLoadingArchivedDetails, setIsLoadingArchivedDetails] = useState(false);
+    const areArchivedDetailsLoadedRef = useRef(false);
+    // Sezioni aperte/collassate, come le ha lasciate l'utente
+    const [sectionsOpen, setSectionsOpen] = useState(getMultiDetailSectionsOpen());
+    // Cambia a ogni cancellazione del layout, per rimontare i pannelli sulle dimensioni di default
+    const [layoutResetToken, setLayoutResetToken] = useState(0);
+    // Layout dell'utente nel local storage: senza non c'è niente da cancellare (è uno stato perché le altezze le salva il panel manager)
+    const [hasSavedLayout, setHasSavedLayout] = useState(hasMultiDetailLayout());
+    // Master
+    const [isOpenMasterForm, setIsOpenMasterForm] = useState(false);
+    const [masterInfoReloadToken, setMasterInfoReloadToken] = useState(0);
+    // Righe del riepilogo
+    const [archiveRows, setArchiveRows] = useState([]);
+    // La modifica in cella aggiorna la riga fuori dallo stato (vedi updateRowValues)
+    const archiveRowsRef = useRef(archiveRows);
+    archiveRowsRef.current = archiveRows;
+    const rowIdRef = useRef(0);
+    // Copia di un dettaglio archiviato in corso: i clic successivi sull'icona vanno ignorati (vedi copyArchivedDetailToRows)
+    const isCopyingArchivedDetailRef = useRef(false);
+    const [focusedRowKey, setFocusedRowKey] = useState(undefined);
+    const [selectedRowKeys, setSelectedRowKeys] = useState([]);
+    // Form di inserimento/modifica di una riga
+    const [isOpenAddForm, setIsOpenAddForm] = useState(false);
+    const [editingRowId, setEditingRowId] = useState(undefined); // Undefined = inserimento
+    const [associationInputMids, setAssociationInputMids] = useState([]); // Associazioni pre-compilate dal master
+    // Archiviazione finale
+    const [stopOnFirstError, setStopOnFirstError] = useState(true);
+    const [isArchiving, setIsArchiving] = useState(false);
+    const selectedItem = detailRelationItems.find(item => item.relation === selectedRelation);
+    const hasMultipleTypes = detailRelationItems.length > 1;
+    const canUpdateMaster = canUpdateMasterCallback(dtd, masterDcmt);
+    // Stessi metadati delle card del master (vedi TMMasterInfoFields): quelli non visibili non contano
+    const masterFieldsCount = useMemo(() => getUserMetadataSorted(dtd).filter(canViewMetadata).length, [dtd]);
+    // Nel riepilogo si mostrano solo le righe del tipo selezionato
+    const currentRows = useMemo(() => archiveRows.filter(r => r.__tid === selectedRelation?.detailTID), [archiveRows, selectedRelation?.detailTID]);
+    const archivedDetailsCount = archivedDetailResults.reduce((total, r) => total + (r.dcmtsFound ?? r.jsonResult?.length ?? 0), 0);
+    // =============================================================================================
+    // MASTER
+    // =============================================================================================
+    /** Identifica il master: cambia quando la navigazione sposta il modale su un altro documento */
+    const masterKey = `${masterDcmt?.TID}_${masterDcmt?.DID}`;
+    // Metadati del master indicizzati per mid: si leggono una sola volta per documento e la cache
+    // si invalida se cambia il master (TID/DID) o dopo un suo salvataggio
+    const masterMetadataCacheRef = useRef(undefined);
+    const getMasterMetadataAsync = () => {
+        if (masterMetadataCacheRef.current?.key !== masterKey) {
+            masterMetadataCacheRef.current = { key: masterKey, promise: getDcmtMetadataByMid(masterDcmt) };
+        }
+        return masterMetadataCacheRef.current.promise;
+    };
+    const handleMasterSavedAsync = async () => {
+        masterMetadataCacheRef.current = undefined;
+        setMasterInfoReloadToken(token => token + 1);
+        setIsOpenMasterForm(false);
+    };
+    // La navigazione ha spostato il modale su un altro master: le righe del riepilogo erano del
+    // documento precedente e sono già state scartate con conferma (vedi navigateMaster).
+    // Il tipo di dettaglio scelto resta: nella lista di provenienza i documenti sono dello stesso tipo
+    const previousMasterKeyRef = useRef(masterKey);
+    useEffect(() => {
+        if (previousMasterKeyRef.current === masterKey)
+            return;
+        previousMasterKeyRef.current = masterKey;
+        setArchiveRows([]);
+        setFocusedRowKey(undefined);
+        setSelectedRowKeys([]);
+        setIsOpenAddForm(false);
+        setEditingRowId(undefined);
+        setIsOpenMasterForm(false);
+    }, [masterKey]);
+    // Associazioni della relazione valorizzate dal master, per pre-compilare il dettaglio
+    const getMasterAssociationsForDetailAsync = async (relation) => {
+        if (!relation)
+            return [];
+        return mapAssociationsFromMetadata(relation, 'detail', await getMasterMetadataAsync());
+    };
+    // =============================================================================================
+    // RELAZIONI E STRUTTURA DEL DETTAGLIO
+    // =============================================================================================
+    // Relazioni di dettaglio archiviabili; con una sola relazione si salta la scelta del tipo.
+    // Dipende dal tipo del master: la navigazione resta nella stessa lista, quindi di norma non cambia
+    useEffect(() => {
+        const loadAsync = async () => {
+            try {
+                setIsLoading(true);
+                TMSpinner.show({ description: SDKUI_Localizator.Loading });
+                const relations = await RelationCacheService.GetAllAsync(SDK_Globals.tmSession);
+                if (!relations)
+                    throw new Error('Impossibile caricare le relazioni.');
+                // Relazioni in cui il tipo corrente è master: i target sono i dettagli archiviabili
+                const detailRelations = relations.filter(r => r.masterTID === dtd?.id
+                    && r.relationType !== RelationTypes.ManyToMany
+                    && r.associations
+                    && r.associations.length > 0);
+                const items = await Promise.all(detailRelations.map(async (relation) => ({
+                    relation,
+                    detailDtd: await getDetailDtdAsync(relation.detailTID),
+                })));
+                setDetailRelationItems(items);
+                if (items.length === 1) {
+                    setSelectedRelation(items[0].relation);
+                    setPhase(MultiDetailArchivePhase.ArchiveSummary);
+                }
+                else {
+                    setPhase(MultiDetailArchivePhase.SelectDcmtType);
+                }
+            }
+            catch (error) {
+                TMExceptionBoxManager.show({ exception: error });
+            }
+            finally {
+                TMSpinner.hide();
+                setIsLoading(false);
+            }
+        };
+        loadAsync();
+    }, [dtd?.id]);
+    // Colonne della griglia di riepilogo e supporto al file del tipo selezionato
+    useEffect(() => {
+        const loadDetailStructureAsync = async () => {
+            if (!selectedRelation?.detailTID) {
+                setDetailColumns([]);
+                setDetailSupportsFile(false);
+                numericMidsRef.current = new Set();
+                return;
+            }
+            try {
+                const detailDtd = await getDetailDtdAsync(selectedRelation.detailTID);
+                setDetailSupportsFile(detailDtd?.archiveConstraint !== ArchiveConstraints.OnlyMetadata);
+                // Liste dati referenziate dai metadati, servono al render delle celle
+                const dataListIDs = new Set();
+                const numericMids = new Set();
+                (detailDtd?.metadata ?? []).forEach(md => {
+                    if (md.dataDomain === MetadataDataDomains.DataList && md.dataListID)
+                        dataListIDs.add(md.dataListID);
+                    if (md.dataType === MetadataDataTypes.Number && md.id !== undefined)
+                        numericMids.add(md.id);
+                });
+                numericMidsRef.current = numericMids;
+                await loadDataListsAsync(dataListIDs);
+                setDetailColumns(buildColumnsFromDtd(detailDtd, renderDataListCell));
+            }
+            catch {
+                setDetailColumns([]);
+                setDetailSupportsFile(false);
+                numericMidsRef.current = new Set();
+            }
+        };
+        loadDetailStructureAsync();
+    }, [selectedRelation?.detailTID]);
+    useEffect(() => {
+        if (phase !== MultiDetailArchivePhase.ArchiveSummary) {
+            setIsSummaryReady(false);
+            return;
+        }
+        setIsSummaryReady(false);
+        const rafId = requestAnimationFrame(() => setIsSummaryReady(true));
+        return () => cancelAnimationFrame(rafId);
+    }, [phase, selectedRelation?.detailTID]);
+    // =============================================================================================
+    // DETTAGLI GIÀ ARCHIVIATI
+    // =============================================================================================
+    const refreshArchivedDetailsAsync = async () => {
+        const detailTID = selectedRelation?.detailTID;
+        if (detailTID === undefined || !masterDcmt?.TID || !masterDcmt?.DID)
+            return;
+        try {
+            setIsLoadingArchivedDetails(true);
+            const searchEngine = SDK_Globals.tmSession?.NewSearchEngine();
+            const results = await searchEngine?.GetAllDetailDcmtsAsync(masterDcmt.TID, masterDcmt.DID) ?? [];
+            let filtered = results.filter(r => selectedRelation?.id !== undefined && r.relationID === selectedRelation.id);
+            if (filtered.length === 0)
+                filtered = results.filter(r => r.fromTID === detailTID);
+            setArchivedDetailResults(filtered);
+            areArchivedDetailsLoadedRef.current = true;
+        }
+        catch (error) {
+            TMExceptionBoxManager.show({ exception: error });
+        }
+        finally {
+            setIsLoadingArchivedDetails(false);
+        }
+    };
+    // I risultati seguono il tipo documento selezionato e il master (che cambia con la navigazione), e si
+    // caricano anche a sezione chiusa: il contatore nella testata e nella barra dei pannelli deve essere
+    // corretto senza dover aprire la sezione
+    useEffect(() => {
+        setArchivedDetailResults([]);
+        areArchivedDetailsLoadedRef.current = false;
+        if (selectedRelation?.detailTID !== undefined)
+            refreshArchivedDetailsAsync();
+    }, [selectedRelation?.detailTID, masterKey]);
+    // =============================================================================================
+    // SEZIONI
+    // =============================================================================================
+    const setSectionOpen = (section, isOpen) => {
+        const next = { ...sectionsOpen, [section]: isOpen };
+        setSectionsOpen(next);
+        saveMultiDetailSectionsOpen(next);
+        // Riaperte tutte le sezioni il collasso torna ai default: senza altezze salvate non c'è più layout
+        setHasSavedLayout(hasMultiDetailLayout());
+        // I dettagli già archiviati sono caricati insieme al tipo di dettaglio: qui si riprova solo se quel caricamento è fallito
+        if (section === 'archivedDetails' && isOpen && !areArchivedDetailsLoadedRef.current && !isLoadingArchivedDetails)
+            refreshArchivedDetailsAsync();
+    };
+    /**
+     * Apre tutte le sezioni senza salvare: serve dove il collasso non è una scelta dell'utente ma una
+     * conseguenza del layout (su mobile si vede un pannello alla volta, e una sezione chiusa lascerebbe
+     * a schermo la sola testata). Non si persiste per non sovrascrivere le sezioni che l'utente ha
+     * chiuso nella vista a pannelli impilati.
+     */
+    const openAllSections = () => {
+        setSectionsOpen(prev => Object.values(prev).every(Boolean) ? prev : { masterInfo: true, archivedDetails: true, archiveList: true });
+        // I dettagli già archiviati sono caricati insieme al tipo di dettaglio: qui si riprova solo se quel caricamento è fallito
+        if (!areArchivedDetailsLoadedRef.current && !isLoadingArchivedDetails)
+            refreshArchivedDetailsAsync();
+    };
+    /**
+     * Cancella il layout configurato dall'utente (altezze dei pannelli e sezioni collassate), previa
+     * conferma. Il token cambia per rimontare il panel manager, che legge le dimensioni solo all'avvio.
+     */
+    const clearLayout = () => {
+        TMMessageBoxManager.show({
+            title: SDKUI_Localizator.RemoveLayout,
+            message: SDKUI_Localizator.RemoveLayout_Confirm,
+            buttons: [ButtonNames.YES, ButtonNames.NO],
+            onButtonClick: (button) => {
+                if (button !== ButtonNames.YES)
+                    return;
+                clearMultiDetailLayout();
+                const restored = getMultiDetailSectionsOpen();
+                setSectionsOpen(restored);
+                setLayoutResetToken(prev => prev + 1);
+                setHasSavedLayout(false);
+                // I dettagli già archiviati sono caricati insieme al tipo di dettaglio: qui si riprova solo se quel caricamento è fallito
+                if (!areArchivedDetailsLoadedRef.current && !isLoadingArchivedDetails)
+                    refreshArchivedDetailsAsync();
+                ShowAlert({ message: SDKUI_Localizator.LayoutRemoved, mode: 'success', title: SDKUI_Localizator.RemoveLayout, duration: 3000 });
+            },
+        });
+    };
+    // =============================================================================================
+    // NAVIGAZIONE
+    // =============================================================================================
+    const selectRelation = (item) => {
+        setSelectedRelation(item.relation);
+        setPhase(MultiDetailArchivePhase.ArchiveSummary);
+    };
+    const backToTypeSelection = () => {
+        setSelectedRelation(undefined);
+        setPhase(MultiDetailArchivePhase.SelectDcmtType);
+    };
+    // Con righe inserite per il tipo corrente il ritorno alla scelta del tipo è bloccato
+    const isBackLocked = currentRows.length > 0;
+    const closeModal = () => {
+        if (archiveRows.length === 0) {
+            onClose();
+            return;
+        }
+        TMMessageBoxManager.show({
+            title: SDKUI_Localizator.Archive,
+            message: SDKUI_Localizator.ExitWithoutArchiving_Confirm,
+            buttons: [ButtonNames.YES, ButtonNames.NO],
+            onButtonClick: (button) => { if (button === ButtonNames.YES)
+                onClose(); },
+        });
+    };
+    // Navigazione del master sulla lista di provenienza: senza la sua callback le frecce non si mostrano
+    const canNavigateMasterPrev = !!onNavigateMaster && (canNavigateMaster?.('prev') ?? false);
+    const canNavigateMasterNext = !!onNavigateMaster && (canNavigateMaster?.('next') ?? false);
+    const isMasterNavigationEnabled = !!onNavigateMaster;
+    /**
+     * Sposta il master sul documento precedente/successivo della lista di provenienza. Le righe già
+     * inserite appartengono al master corrente: si perdono, quindi prima si chiede conferma
+     */
+    const navigateMaster = (dir) => {
+        if (!onNavigateMaster)
+            return;
+        if (dir === 'prev' ? !canNavigateMasterPrev : !canNavigateMasterNext)
+            return;
+        if (archiveRows.length === 0) {
+            onNavigateMaster(dir);
+            return;
+        }
+        TMMessageBoxManager.show({
+            title: SDKUI_Localizator.Archive,
+            message: SDKUI_Localizator.ChangeMasterWithoutArchiving_Confirm,
+            buttons: [ButtonNames.YES, ButtonNames.NO],
+            // Le righe le azzera l'effetto sul cambio di master, non serve svuotarle qui
+            onButtonClick: (button) => { if (button === ButtonNames.YES)
+                onNavigateMaster(dir); },
+        });
+    };
+    // =============================================================================================
+    // RIGHE DEL RIEPILOGO
+    // =============================================================================================
+    const openAddForm = () => {
+        if (!selectedRelation?.detailTID)
+            return;
+        setEditingRowId(undefined);
+        setIsOpenAddForm(true);
+    };
+    // Identità stabile: la griglia dei dettagli la usa nelle sue callback memoizzate
+    const openEditForm = useCallback((row) => {
+        if (!row)
+            return;
+        setEditingRowId(row.id);
+        setIsOpenAddForm(true);
+    }, []);
+    const closeAddForm = () => {
+        setEditingRowId(undefined);
+        setIsOpenAddForm(false);
+    };
+    const deleteRow = useCallback((row) => {
+        if (!row)
+            return;
+        TMMessageBoxManager.show({
+            title: SDKUI_Localizator.Remove,
+            message: SDKUI_Localizator.RemoveDetailFromSummary_Confirm,
+            buttons: [ButtonNames.YES, ButtonNames.NO],
+            onButtonClick: (button) => {
+                if (button !== ButtonNames.YES)
+                    return;
+                setArchiveRows(prev => prev.filter(r => r.id !== row.id));
+                setFocusedRowKey(prev => (prev === row.id ? undefined : prev));
+                setSelectedRowKeys(prev => prev.filter(k => k !== row.id));
+            },
+        });
+    }, []);
+    // I valori del form sono stringhe: le celle numeriche vogliono il numero, richiesto dal loro editor
+    const buildArchiveRow = useCallback((id, tid, values, file) => {
+        const row = { id, __tid: tid, __values: values, __file: file };
+        for (const v of values) {
+            if (v.mid === undefined)
+                continue;
+            row[String(v.mid)] = numericMidsRef.current.has(v.mid) ? toGridNumber(v.value) : (v.value ?? '');
+        }
+        return row;
+    }, []);
+    // Aggiunge/aggiorna nel riepilogo la riga compilata nel form, senza archiviare a sistema
+    const upsertRow = (values, file) => {
+        const tid = selectedRelation?.detailTID;
+        if (tid === undefined)
+            return;
+        if (editingRowId !== undefined) {
+            setArchiveRows(prev => prev.map(r => (r.id === editingRowId ? buildArchiveRow(editingRowId, tid, values, file) : r)));
+        }
+        else {
+            rowIdRef.current += 1;
+            setArchiveRows(prev => [...prev, buildArchiveRow(rowIdRef.current, tid, values, file)]);
+        }
+        closeAddForm();
+    };
+    /**
+     * Modifica diretta in griglia di uno o più metadati testuali o numerici (changes: mid -> valore).
+     * La riga è aggiornata sul posto e non con setArchiveRows: un nuovo riferimento all'array
+     * ricaricherebbe la griglia a ogni cella confermata, perdendo il clic sulla cella successiva.
+     * L'array __values è sostituito, non modificato: il duplicato, che lo condivide, resta invariato
+     */
+    const updateRowValues = useCallback((rowId, changes) => {
+        const changedMids = Object.keys(changes);
+        if (changedMids.length === 0)
+            return;
+        const row = archiveRowsRef.current.find(r => r.id === rowId);
+        if (!row)
+            return;
+        // I __values vanno a sistema come stringhe, anche quelli che in griglia sono numeri. La griglia
+        // restituisce null sull'editor svuotato: a sistema il metadato va vuoto, non nullo
+        const normalized = {};
+        changedMids.forEach(mid => { normalized[mid] = changes[mid] === null || changes[mid] === undefined ? '' : String(changes[mid]); });
+        const values = row.__values.map(v => (v.mid !== undefined && normalized[String(v.mid)] !== undefined
+            ? { ...v, value: normalized[String(v.mid)] }
+            : v));
+        // Un metadato assente dai valori del form non arriverebbe all'archiviazione
+        changedMids.filter(mid => !values.some(v => String(v.mid) === mid)).forEach(mid => {
+            const added = new MetadataValueDescriptorEx();
+            added.tid = row.__tid;
+            added.mid = Number(mid);
+            added.value = normalized[mid];
+            values.push(added);
+        });
+        row.__values = values;
+        // In cella il numero resta un numero, come lo vuole il suo editor
+        changedMids.forEach(mid => { row[mid] = numericMidsRef.current.has(Number(mid)) ? toGridNumber(normalized[mid]) : normalized[mid]; });
+    }, []);
+    // I __values sono condivisi per riferimento: la modifica sostituisce l'intero array, quindi non intacca il duplicato
+    const duplicateRow = useCallback((row) => {
+        if (!row)
+            return;
+        rowIdRef.current += 1;
+        setArchiveRows(prev => [...prev, buildArchiveRow(rowIdRef.current, row.__tid, row.__values, row.__file)]);
+    }, [buildArchiveRow]);
+    /**
+     * Copia un dettaglio già archiviato tra le righe da archiviare: i suoi metadati (e il file, se il
+     * tipo lo prevede e il documento ne ha uno) diventano una nuova riga del riepilogo. Il documento
+     * archiviato non è toccato: quello che si ottiene è un nuovo dettaglio, ancora da archiviare.
+     * I numeratori non si copiano, il loro valore lo assegna il sistema all'archiviazione.
+     * Ogni motivo che impedisce la copia, o che la rende parziale, arriva all'utente con un avviso:
+     * la riga entra nel riepilogo solo se i metadati del dettaglio sono stati letti davvero.
+     */
+    const copyArchivedDetailToRows = async (dcmt) => {
+        // Clic ripetuti sull'icona: una copia alla volta, altrimenti spinner e righe si sovrappongono
+        if (isCopyingArchivedDetailRef.current)
+            return;
+        try {
+            const detailTID = selectedRelation?.detailTID;
+            // Senza tipo selezionato il riepilogo non ha colonne in cui copiare il dettaglio
+            if (detailTID === undefined) {
+                ShowAlert({ message: SDKUI_Localizator.SelectDcmtTypeForDetailArchiving, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 3000 });
+                return;
+            }
+            // La griglia dei risultati porta i valori di riga come stringhe: TID e DID vanno usati come numeri
+            const archivedDcmt = { TID: Number(dcmt?.TID), DID: Number(dcmt?.DID) };
+            if (!Number.isFinite(archivedDcmt.TID) || !Number.isFinite(archivedDcmt.DID) || archivedDcmt.TID <= 0 || archivedDcmt.DID <= 0) {
+                ShowAlert({ message: SDKUI_Localizator.InvalidDcmt, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 3000 });
+                return;
+            }
+            // Le righe del riepilogo sono del tipo selezionato: un dettaglio di altro tipo non ne ha le colonne
+            if (archivedDcmt.TID !== detailTID) {
+                ShowAlert({ message: SDKUI_Localizator.DetailNotOfSelectedDcmtType, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 3000 });
+                return;
+            }
+            isCopyingArchivedDetailRef.current = true;
+            TMSpinner.show({ description: SDKUI_Localizator.Loading });
+            const [detailDtd, metadataByMid] = await Promise.all([getDetailDtdAsync(detailTID), getDcmtMetadataByMid(archivedDcmt)]);
+            // Senza la struttura del tipo non si sa quali metadati copiare: la riga nascerebbe vuota
+            if (!detailDtd) {
+                ShowAlert({ message: SDKUI_Localizator.DcmtTypeStructureNotRetrieved, mode: 'error', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                return;
+            }
+            // Il permesso serve comunque all'archiviazione: dirlo qui evita di compilare righe inutili
+            if (!canArchive(detailDtd)) {
+                ShowAlert({ message: SDKUI_Localizator.YouDoNotHavePermissionsToArchiveDetailDocumentsOfThisType, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                return;
+            }
+            // Metadati non letti (sessione non valida, documento non più visibile): una riga di valori vuoti non serve
+            if (metadataByMid.size === 0) {
+                ShowAlert({ message: SDKUI_Localizator.DetailMetadataNotRetrieved, mode: 'error', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                return;
+            }
+            const userMetadata = getUserMetadataSorted(detailDtd);
+            const archivableMetadata = userMetadata.filter(md => md.dataDomain !== MetadataDataDomains.Numerator && handleArchiveVisibility(md));
+            // Niente da copiare: il tipo non ha metadati utente, o nessuno di questi è archiviabile
+            if (archivableMetadata.length === 0) {
+                const message = userMetadata.length > 0
+                    ? SDKUI_Localizator.YouDoNotHavePermissionsToArchiveDetailDocumentsOfThisType
+                    : SDKUI_Localizator.DetailMetadataNotRetrieved;
+                ShowAlert({ message, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                return;
+            }
+            // Gli stessi metadati che compila il form della riga: valori come stringhe, mancanti a vuoto
+            const values = archivableMetadata.map(md => {
+                const mvd = new MetadataValueDescriptorEx();
+                mvd.tid = detailTID;
+                mvd.mid = md.id;
+                mvd.md = md;
+                // Date e numeri nel formato del form: la riga copiata si rilegge e si modifica come le altre
+                mvd.value = toArchiveRowValue(metadataByMid.get(md.id), md.dataType);
+                mvd.isRequired = md.isRequired?.toString();
+                return mvd;
+            });
+            // Il file segue la riga solo se il tipo lo prevede e il documento ne ha uno; se non si
+            // recupera la riga si inserisce comunque, il file si aggiunge dal form della riga
+            let file = undefined;
+            // Il file c'è se lo dice il metadato di sistema del documento: la colonna della griglia
+            // dei risultati è solo un ripiego, la ricerca potrebbe non averla tra i suoi valori
+            const fileExt = String(metadataByMid.get(SystemMIDsAsNumber.FileExt) ?? dcmt?.FILEEXT ?? '');
+            const hasFile = fileExt !== '';
+            const supportsFile = detailDtd.archiveConstraint !== ArchiveConstraints.OnlyMetadata;
+            if (hasFile && supportsFile) {
+                if (detailDtd.perm?.canRetrieveFile !== AccessLevels.Yes) {
+                    ShowAlert({ message: `${SDKUI_Localizator.DetailFileNotRetrieved}: ${SDKUI_Localizator.YouDoNotHavePermissionsToRetrieveTheFile}`, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                }
+                else {
+                    try {
+                        const rfo = new RetrieveFileOptions();
+                        rfo.retrieveReason = DcmtOpers.None;
+                        rfo.generalRetrieveFormat = GeneralRetrieveFormats.OriginalUnsigned;
+                        file = await SDK_Globals.tmSession?.NewSearchEngine().RetrieveFileAsync(archivedDcmt.TID, archivedDcmt.DID, rfo);
+                        // Nessun errore ma nemmeno il file (sessione non valida): l'utente deve saperlo
+                        if (!file)
+                            ShowAlert({ message: SDKUI_Localizator.DetailFileNotRetrieved, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                    }
+                    catch (error) {
+                        ShowAlert({ message: `${SDKUI_Localizator.DetailFileNotRetrieved}: ${getExceptionMessage(error)}`, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+                    }
+                }
+            }
+            rowIdRef.current += 1;
+            const newRowId = rowIdRef.current;
+            setArchiveRows(prev => [...prev, buildArchiveRow(newRowId, detailTID, values, file)]);
+            // La riga copiata è quella su cui si lavora: fuoco e selezione la seguono
+            setFocusedRowKey(newRowId);
+            setSelectedRowKeys([newRowId]);
+            // Con la sezione chiusa la riga appena copiata non si vedrebbe
+            if (!sectionsOpen.archiveList)
+                setSectionOpen('archiveList', true);
+            ShowAlert({ message: SDKUI_Localizator.DetailCopiedToArchiveList, mode: 'success', title: SDKUI_Localizator.Duplicate, duration: 3000 });
+            // Il tipo pretende il file: senza, la riga non passerebbe l'archiviazione
+            if (!file && detailDtd.archiveConstraint === ArchiveConstraints.ContentCompulsory) {
+                ShowAlert({ message: SDKUI_Localizator.DetailFileToAddFromRowForm, mode: 'warning', title: SDKUI_Localizator.Duplicate, duration: 5000 });
+            }
+        }
+        catch (error) {
+            TMExceptionBoxManager.show({ exception: error });
+        }
+        finally {
+            // Spinner e blocco partono insieme: se la copia non è nemmeno iniziata non c'è niente da chiudere
+            if (isCopyingArchivedDetailRef.current) {
+                isCopyingArchivedDetailRef.current = false;
+                TMSpinner.hide();
+            }
+        }
+    };
+    // All'apertura del form pre-compila i MID di collegamento valorizzati dal master
+    useEffect(() => {
+        if (!isOpenAddForm || !selectedRelation) {
+            setAssociationInputMids([]);
+            return;
+        }
+        let cancelled = false;
+        getMasterAssociationsForDetailAsync(selectedRelation)
+            .then(associations => { if (!cancelled)
+            setAssociationInputMids(associations); })
+            .catch(() => { if (!cancelled)
+            setAssociationInputMids([]); });
+        return () => { cancelled = true; };
+    }, [isOpenAddForm, selectedRelation]);
+    // MID pre-compilati: in inserimento i collegamenti dal master, in modifica i valori della riga
+    const editingRow = editingRowId !== undefined ? archiveRows.find(r => r.id === editingRowId) : undefined;
+    const nextFormInputMids = editingRow
+        ? editingRow.__values
+            .filter(v => v.mid !== undefined && v.value !== undefined && v.value !== null && v.value !== '')
+            .map(v => ({ mid: v.mid, value: String(v.value) }))
+        : associationInputMids;
+    // Il form riapplica i valori quando cambia il riferimento di inputMids: si mantiene la stessa
+    // istanza finché il contenuto non cambia, così le modifiche dell'utente non vengono sovrascritte
+    const formInputMidsSignature = nextFormInputMids.map(o => `${o.mid}=${o.value}`).join('|');
+    const formInputMidsRef = useRef(nextFormInputMids);
+    const formInputMidsSignatureRef = useRef(formInputMidsSignature);
+    if (formInputMidsSignatureRef.current !== formInputMidsSignature) {
+        formInputMidsSignatureRef.current = formInputMidsSignature;
+        formInputMidsRef.current = nextFormInputMids;
+    }
+    const formInputMids = formInputMidsRef.current;
+    // =============================================================================================
+    // ARCHIVIAZIONE
+    // =============================================================================================
+    // Archivia solo le righe del tipo corrente: quelle di altri tipi restano intatte
+    const archiveAllAsync = async () => {
+        const detailTID = selectedRelation?.detailTID;
+        if (detailTID === undefined)
+            return;
+        const rowsToArchive = archiveRows.filter(r => r.__tid === detailTID);
+        if (rowsToArchive.length === 0) {
+            ShowAlert({ message: SDKUI_Localizator.NoDataToDisplay, mode: 'warning', title: SDKUI_Localizator.Archive, duration: 3000 });
+            return;
+        }
+        try {
+            setIsArchiving(true);
+            const detailDtd = await getDetailDtdAsync(detailTID);
+            if (!canArchive(detailDtd)) {
+                ShowAlert({ message: SDKUI_Localizator.YouDoNotHavePermissionsToArchiveDetailDocumentsOfThisType, mode: 'warning', title: SDKUI_Localizator.Archive, duration: 5000 });
+                return;
+            }
+            const dataTypeByMid = new Map();
+            (detailDtd?.metadata ?? []).forEach(md => { if (md.id !== undefined)
+                dataTypeByMid.set(md.id, md.dataType); });
+            // Collegamenti della relazione valorizzati dal master (prevalgono sui valori del form)
+            const associationMids = await getMasterAssociationsForDetailAsync(selectedRelation);
+            // Con piu' righe: primaria sui documenti, secondaria sui byte. Con una riga sola solo i byte.
+            const isBatch = rowsToArchive.length > 1;
+            const waitPanel = TMWaitPanelManager.show({
+                title: SDKUI_Localizator.Archiving,
+                max: isBatch ? rowsToArchive.length : 0,
+                cancelable: true,
+                showSecondary: isBatch,
+                showCounters: isBatch,
+                primaryLabel: isBatch ? SDKUI_Localizator.Documents : undefined,
+                secondaryLabel: isBatch ? 'File corrente' : undefined,
+            });
+            const publishBytes = (loaded, total) => {
+                const text = total > 0
+                    ? `Uploading... ${Globalization.getNumberDisplayValue(loaded, true)} / ${Globalization.getNumberDisplayValue(total, true)}`
+                    : '';
+                if (isBatch)
+                    waitPanel.setSecondary({ value: loaded, max: total, text });
+                else
+                    waitPanel.update({ value: loaded, max: total, subtitle: text });
+            };
+            const result = [];
+            const archivedRowIds = new Set();
+            try {
+                for (let i = 0; i < rowsToArchive.length; i++) {
+                    // Con la conferma di interruzione aperta il loop resta in pausa qui
+                    await waitPanel.waitWhilePaused();
+                    if (waitPanel.aborted) {
+                        result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
+                        waitPanel.warning();
+                        break;
+                    }
+                    if (isBatch)
+                        waitPanel.setSubtitle(`${SDKUI_Localizator.Archiving} ${i + 1} / ${rowsToArchive.length}`);
+                    const rowData = rowsToArchive[i];
+                    try {
+                        const newDID = await archiveRowAsync(rowData, detailTID, dataTypeByMid, associationMids, waitPanel.signal, publishBytes);
+                        archivedRowIds.add(rowData.id);
+                        result.push({ rowIndex: i, id1: detailTID, id2: newDID, resultType: ResultTypes.SUCCESS });
+                        waitPanel.ok();
+                    }
+                    catch (error) {
+                        const err = error;
+                        // Annullamento richiesto dall'utente: interrompe senza mostrare l'errore
+                        if (err?.name === 'CanceledError' || waitPanel.aborted) {
+                            result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
+                            waitPanel.warning();
+                            break;
+                        }
+                        result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.ERROR, description: getExceptionMessage(error) });
+                        waitPanel.error();
+                        if (stopOnFirstError)
+                            break;
+                    }
+                    // Avanza a elaborazione conclusa: la barra non arriva al 100% prima dell'ultimo documento
+                    if (isBatch)
+                        await waitPanel.step();
+                }
+            }
+            finally {
+                // Chiuso prima del riepilogo dei risultati
+                waitPanel.close();
+            }
+            // Le righe archiviate escono dal riepilogo
+            if (archivedRowIds.size > 0) {
+                setArchiveRows(prev => prev.filter(r => !archivedRowIds.has(r.id)));
+                setSelectedRowKeys([]);
+                setFocusedRowKey(undefined);
+                refreshArchivedDetailsAsync();
+            }
+            const successCount = result.filter(o => o.resultType === ResultTypes.SUCCESS).length;
+            const successMsg = `${successCount} ${successCount === 1 ? 'documento di dettaglio archiviato' : 'documenti di dettaglio archiviati'} con successo`;
+            TMResultManager.show(result, SDKUI_Localizator.Archive, 'TID', 'DID', successMsg);
+            // Tutte le righe del tipo corrente archiviate senza errori: il modale si chiude
+            const errorCount = result.filter(o => o.resultType === ResultTypes.ERROR).length;
+            if (errorCount === 0 && archivedRowIds.size === rowsToArchive.length)
+                onClose();
+        }
+        catch (error) {
+            TMExceptionBoxManager.show({ exception: error });
+        }
+        finally {
+            setIsArchiving(false);
+        }
+    };
+    // Archiviazione di una singola riga, con avanzamento dell'upload notificato a onBytes
+    const archiveRowAsync = async (row, detailTID, dataTypeByMid, associationMids, signal, onBytes) => {
+        const ae = new ArchiveEngineByID(SDK_Globals.tmSession);
+        ae.TID = detailTID;
+        ae.Metadata_ClearAll();
+        // Valori del form + associazioni con il master (le associazioni prevalgono). I metadati di
+        // sistema (TID, DID, FILEEXT...) non si archiviano: li assegna il sistema e mandarli fa fallire
+        // l'archiviazione. Il form li esclude già (vedi useArchiveListForm), qui è la rete di sicurezza
+        // per le righe che arrivano da altre strade, come la copia di un dettaglio già archiviato
+        const valueByMid = new Map();
+        for (const v of row.__values) {
+            if (v.mid !== undefined && v.mid > 99 && v.value)
+                valueByMid.set(v.mid, v.value);
+        }
+        for (const a of associationMids) {
+            if (a.mid > 99 && a.value)
+                valueByMid.set(a.mid, a.value);
+        }
+        valueByMid.forEach((value, mid) => {
+            switch (dataTypeByMid.get(mid)) {
+                case MetadataDataTypes.DateTime:
+                    ae.Metadata_AddDateTime(mid, new Date(value));
+                    break;
+                case MetadataDataTypes.Number:
+                    ae.Metadata_AddNumber(mid, parseFloat(value));
+                    break;
+                default:
+                    ae.Metadata_AddString(mid, value);
+                    break;
+            }
+        });
+        if (row.__file)
+            ae.ArchivingFile = row.__file;
+        return ae.ArchiveAsync(signal, (pd) => {
+            // Upload completato: la barra si azzera per il file successivo
+            if (pd.ProgressBarValue === pd.ProgressBarMaximum)
+                onBytes(0, 0);
+            else
+                onBytes(pd.ProgressBarValue ?? 0, pd.ProgressBarMaximum ?? 0);
+        });
+    };
+    return {
+        // Flusso
+        isLoading, isSummaryReady, phase, setPhase,
+        detailRelationItems, selectedRelation, selectedItem, hasMultipleTypes,
+        selectRelation, backToTypeSelection, isBackLocked, closeModal,
+        // Navigazione del master sulla lista di provenienza
+        isMasterNavigationEnabled, canNavigateMasterPrev, canNavigateMasterNext, navigateMaster,
+        // Sezioni
+        sectionsOpen, setSectionOpen, openAllSections, clearLayout, layoutResetToken,
+        hasSavedLayout, setHasSavedLayout,
+        // Master
+        canUpdateMaster, masterFieldsCount, getMasterMetadataAsync, masterInfoReloadToken,
+        isOpenMasterForm, setIsOpenMasterForm, handleMasterSavedAsync,
+        // Dettagli già archiviati
+        archivedDetailResults, archivedDetailsCount, isLoadingArchivedDetails, refreshArchivedDetailsAsync,
+        // Dettagli da archiviare
+        detailColumns, detailSupportsFile, archiveRows, currentRows,
+        focusedRowKey, setFocusedRowKey, selectedRowKeys, setSelectedRowKeys,
+        isOpenAddForm, editingRowId, editingRow, formInputMids,
+        openAddForm, openEditForm, closeAddForm, deleteRow, duplicateRow, upsertRow, updateRowValues, copyArchivedDetailToRows,
+        // Archiviazione
+        stopOnFirstError, setStopOnFirstError, isArchiving, archiveAllAsync,
+    };
+};