@topconsultnpm/sdkui-react 6.22.0-dev2.19 → 6.22.0-dev2.20

package/lib/hooks/useMultiMasterDetailDcmts.d.ts

@@ -0,0 +1,97 @@
+import { DcmtTypeDescriptor, RelationDescriptor, SearchResultDescriptor } from '@topconsultnpm/sdk-ts';
+import { IColumnProps } from 'devextreme-react/data-grid';
+import { DcmtInfo, MetadataValueDescriptorEx } from '../ts';
+import { AccordionSection, ArchiveRow, ArchiveRowChanges, DetailRelationItem, MetadataScalarValue } from '../components/features/documents/TMMultiMasterDetailDcmtsUtils';
+/** Fasi del flusso di archiviazione multipla dei dettagli */
+export declare enum MultiDetailArchivePhase {
+    /** Scelta del tipo documento */
+    SelectDcmtType = 0,
+    /** Riepilogo delle archiviazioni */
+    ArchiveSummary = 1
+}
+/** Riga di riepilogo: definita con i tipi della feature (vedi TMMultiMasterDetailDcmtsUtils) */
+export type { ArchiveRow };
+/** Coppia mid/valore per pre-compilare il form */
+export type MidValue = {
+    mid: number;
+    value: string;
+};
+/** Stato del wait panel: le chiavi sono quelle dei props di TMLayoutWaitingContainer */
+export type WaitPanelState = {
+    showWaitPanel: boolean;
+    waitPanelTitle: string;
+    showWaitPanelPrimary: boolean;
+    waitPanelTextPrimary: string;
+    waitPanelValuePrimary: number;
+    waitPanelMaxValuePrimary: number;
+    showWaitPanelSecondary: boolean;
+    waitPanelTextSecondary: string;
+    waitPanelValueSecondary: number;
+    waitPanelMaxValueSecondary: number;
+};
+interface UseMultiMasterDetailDcmtsParams {
+    /** Tipo documento del master */
+    dtd: DcmtTypeDescriptor;
+    /** Documento master da cui parte l'archiviazione dei dettagli */
+    masterDcmt: DcmtInfo;
+    /** Chiusura del modale */
+    onClose: () => void;
+}
+/**
+ * Logica dell'archiviazione multipla dei dettagli: relazioni, sezioni, righe del riepilogo e
+ * archiviazione. Il rendering sta in TMMultiMasterDetailDcmtsForm
+ */
+export declare const useMultiMasterDetailDcmts: ({ dtd, masterDcmt, onClose }: UseMultiMasterDetailDcmtsParams) => {
+    isLoading: boolean;
+    isSummaryReady: boolean;
+    phase: MultiDetailArchivePhase;
+    setPhase: import("react").Dispatch<import("react").SetStateAction<MultiDetailArchivePhase>>;
+    detailRelationItems: DetailRelationItem[];
+    selectedRelation: RelationDescriptor | undefined;
+    selectedItem: DetailRelationItem | undefined;
+    hasMultipleTypes: boolean;
+    selectRelation: (item: DetailRelationItem) => void;
+    backToTypeSelection: () => void;
+    isBackLocked: boolean;
+    closeModal: () => void;
+    sectionsOpen: Record<AccordionSection, boolean>;
+    setSectionOpen: (section: AccordionSection, isOpen: boolean) => void;
+    clearLayout: () => void;
+    layoutResetToken: number;
+    canUpdateMaster: boolean;
+    masterFieldsCount: number;
+    getMasterMetadataAsync: () => Promise<Map<number, MetadataScalarValue>>;
+    masterInfoReloadToken: number;
+    isOpenMasterForm: boolean;
+    setIsOpenMasterForm: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    handleMasterSavedAsync: () => Promise<void>;
+    archivedDetailResults: SearchResultDescriptor[];
+    archivedDetailsCount: number;
+    isLoadingArchivedDetails: boolean;
+    refreshArchivedDetailsAsync: () => Promise<void>;
+    detailColumns: IColumnProps[];
+    detailSupportsFile: boolean;
+    archiveRows: ArchiveRow[];
+    currentRows: ArchiveRow[];
+    focusedRowKey: number | undefined;
+    setFocusedRowKey: import("react").Dispatch<import("react").SetStateAction<number | undefined>>;
+    selectedRowKeys: number[];
+    setSelectedRowKeys: import("react").Dispatch<import("react").SetStateAction<number[]>>;
+    isOpenAddForm: boolean;
+    editingRowId: number | undefined;
+    editingRow: ArchiveRow | undefined;
+    formInputMids: MidValue[];
+    openAddForm: () => void;
+    openEditForm: (row: ArchiveRow | undefined) => void;
+    closeAddForm: () => void;
+    deleteRow: (row: ArchiveRow | undefined) => void;
+    duplicateRow: (row: ArchiveRow | undefined) => void;
+    upsertRow: (values: Array<MetadataValueDescriptorEx>, file: File | undefined) => void;
+    updateRowValues: (rowId: number, changes: ArchiveRowChanges) => void;
+    stopOnFirstError: boolean;
+    setStopOnFirstError: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    isArchiving: boolean;
+    archiveAllAsync: () => Promise<void>;
+    waitPanel: WaitPanelState;
+    abortController: AbortController | undefined;
+};

package/lib/hooks/useMultiMasterDetailDcmts.js

@@ -0,0 +1,555 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { ArchiveConstraints, ArchiveEngineByID, MetadataDataDomains, MetadataDataTypes, RelationCacheService, RelationTypes, ResultTypes, SDK_Globals } from '@topconsultnpm/sdk-ts';
+import { MetadataValueDescriptorEx } from '../ts';
+import { clearMultiDetailLayout, Globalization, getExceptionMessage, getMultiDetailSectionsOpen, saveMultiDetailSectionsOpen, SDKUI_Localizator } from '../helper';
+import { getDcmtMetadataByMid, getUserMetadataSorted, mapAssociationsFromMetadata } from '../helper/dcmtsHelper';
+import { ButtonNames, TMExceptionBoxManager, TMMessageBoxManager } from '../components/base/TMPopUp';
+import TMSpinner from '../components/base/TMSpinner';
+import ShowAlert from '../components/base/TMAlert';
+import { TMResultManager } from '../components/forms/TMResultDialog';
+import { useDataListItem } from './useDataListItem';
+import { buildColumnsFromDtd, canArchive, canUpdateMasterCallback, getDetailDtdAsync } 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 = {}));
+const CLOSED_WAIT_PANEL = {
+    showWaitPanel: false,
+    waitPanelTitle: '',
+    showWaitPanelPrimary: false,
+    waitPanelTextPrimary: '',
+    waitPanelValuePrimary: 0,
+    waitPanelMaxValuePrimary: 0,
+    showWaitPanelSecondary: false,
+    waitPanelTextSecondary: '',
+    waitPanelValueSecondary: 0,
+    waitPanelMaxValueSecondary: 0,
+};
+/**
+ * Logica dell'archiviazione multipla dei dettagli: relazioni, sezioni, righe del riepilogo e
+ * archiviazione. Il rendering sta in TMMultiMasterDetailDcmtsForm
+ */
+export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose }) => {
+    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);
+    // 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);
+    // Master
+    const [isOpenMasterForm, setIsOpenMasterForm] = useState(false);
+    const [masterInfoReloadToken, setMasterInfoReloadToken] = useState(0);
+    // Righe del riepilogo
+    const [archiveRows, setArchiveRows] = useState([]);
+    const rowIdRef = useRef(0);
+    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 [waitPanel, setWaitPanel] = useState(CLOSED_WAIT_PANEL);
+    const abortControllerRef = useRef(undefined);
+    const selectedItem = detailRelationItems.find(item => item.relation === selectedRelation);
+    const hasMultipleTypes = detailRelationItems.length > 1;
+    const canUpdateMaster = canUpdateMasterCallback(dtd, masterDcmt);
+    const masterFieldsCount = useMemo(() => getUserMetadataSorted(dtd).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
+    // =============================================================================================
+    // Metadati del master indicizzati per mid: il master è fisso, quindi si legge una sola volta
+    // e la cache si invalida solo se cambia il documento (TID/DID) o dopo un salvataggio
+    const masterMetadataCacheRef = useRef(undefined);
+    const getMasterMetadataAsync = () => {
+        const key = `${masterDcmt?.TID}_${masterDcmt?.DID}`;
+        if (masterMetadataCacheRef.current?.key !== key) {
+            masterMetadataCacheRef.current = { key, promise: getDcmtMetadataByMid(masterDcmt) };
+        }
+        return masterMetadataCacheRef.current.promise;
+    };
+    const handleMasterSavedAsync = async () => {
+        masterMetadataCacheRef.current = undefined;
+        setMasterInfoReloadToken(token => token + 1);
+        setIsOpenMasterForm(false);
+    };
+    // 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
+    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();
+    }, []);
+    // Colonne della griglia di riepilogo e supporto al file del tipo selezionato
+    useEffect(() => {
+        const loadDetailStructureAsync = async () => {
+            if (!selectedRelation?.detailTID) {
+                setDetailColumns([]);
+                setDetailSupportsFile(false);
+                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();
+                (detailDtd?.metadata ?? []).forEach(md => {
+                    if (md.dataDomain === MetadataDataDomains.DataList && md.dataListID)
+                        dataListIDs.add(md.dataListID);
+                });
+                await loadDataListsAsync(dataListIDs);
+                setDetailColumns(buildColumnsFromDtd(detailDtd, renderDataListCell));
+            }
+            catch {
+                setDetailColumns([]);
+                setDetailSupportsFile(false);
+            }
+        };
+        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
+    useEffect(() => {
+        setArchivedDetailResults([]);
+        areArchivedDetailsLoadedRef.current = false;
+        if (selectedRelation?.detailTID !== undefined && sectionsOpen.archivedDetails)
+            refreshArchivedDetailsAsync();
+    }, [selectedRelation?.detailTID]);
+    // =============================================================================================
+    // SEZIONI
+    // =============================================================================================
+    const setSectionOpen = (section, isOpen) => {
+        const next = { ...sectionsOpen, [section]: isOpen };
+        setSectionsOpen(next);
+        saveMultiDetailSectionsOpen(next);
+        // I dettagli già archiviati si caricano alla prima apertura della sezione
+        if (section === 'archivedDetails' && isOpen && !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: 'Cancella layout',
+            message: 'Vuoi cancellare il layout?',
+            buttons: [ButtonNames.YES, ButtonNames.NO],
+            onButtonClick: (button) => {
+                if (button !== ButtonNames.YES)
+                    return;
+                clearMultiDetailLayout();
+                const restored = getMultiDetailSectionsOpen();
+                setSectionsOpen(restored);
+                setLayoutResetToken(prev => prev + 1);
+                // Le sezioni riaperte dal ripristino caricano i dettagli già archiviati come alla prima apertura
+                if (restored.archivedDetails && !areArchivedDetailsLoadedRef.current && !isLoadingArchivedDetails)
+                    refreshArchivedDetailsAsync();
+                ShowAlert({ message: 'Layout cancellato', mode: 'success', title: 'Cancella layout', 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(); },
+        });
+    };
+    // =============================================================================================
+    // 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));
+            },
+        });
+    }, []);
+    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)
+                row[String(v.mid)] = 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 (changes: mid -> valore).
+     * La riga e i suoi __values sono ricreati: il duplicato, che condivide __values per
+     * riferimento, resta invariato
+     */
+    const updateRowValues = useCallback((rowId, changes) => {
+        const changedMids = Object.keys(changes);
+        if (changedMids.length === 0)
+            return;
+        // La griglia restituisce null sull'editor svuotato: a sistema il metadato va vuoto, non nullo
+        const normalized = {};
+        changedMids.forEach(mid => { normalized[mid] = changes[mid] ?? ''; });
+        setArchiveRows(prev => prev.map(r => {
+            if (r.id !== rowId)
+                return r;
+            const values = r.__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 = r.__tid;
+                added.mid = Number(mid);
+                added.value = normalized[mid];
+                values.push(added);
+            });
+            const updated = { ...r, __values: values };
+            changedMids.forEach(mid => { updated[mid] = normalized[mid]; });
+            return updated;
+        }));
+    }, []);
+    // 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]);
+    // 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);
+            // Barra primaria: avanzamento documenti. Barra secondaria: upload del file corrente
+            const abortController = new AbortController();
+            abortControllerRef.current = abortController;
+            setWaitPanel({
+                ...CLOSED_WAIT_PANEL,
+                showWaitPanel: true,
+                waitPanelTitle: SDKUI_Localizator.Archiving,
+                showWaitPanelPrimary: rowsToArchive.length > 1,
+                waitPanelMaxValuePrimary: rowsToArchive.length,
+                showWaitPanelSecondary: true,
+            });
+            const result = [];
+            const archivedRowIds = new Set();
+            for (let i = 0; i < rowsToArchive.length; i++) {
+                if (abortController.signal.aborted) {
+                    result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
+                    break;
+                }
+                const rowData = rowsToArchive[i];
+                try {
+                    setWaitPanel(prev => ({ ...prev, waitPanelTextPrimary: `${SDKUI_Localizator.Archiving} ${i + 1} / ${rowsToArchive.length}` }));
+                    const newDID = await archiveRowAsync(rowData, detailTID, dataTypeByMid, associationMids, abortController.signal);
+                    setWaitPanel(prev => ({ ...prev, waitPanelValuePrimary: i + 1 }));
+                    archivedRowIds.add(rowData.id);
+                    result.push({ rowIndex: i, id1: detailTID, id2: newDID, resultType: ResultTypes.SUCCESS });
+                }
+                catch (error) {
+                    const err = error;
+                    // Annullamento richiesto dall'utente: interrompe senza mostrare l'errore
+                    if (err?.name === 'CanceledError' || abortController.signal.aborted) {
+                        result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
+                        break;
+                    }
+                    result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.ERROR, description: getExceptionMessage(error) });
+                    if (stopOnFirstError)
+                        break;
+                }
+            }
+            // Le righe archiviate escono dal riepilogo
+            if (archivedRowIds.size > 0) {
+                setArchiveRows(prev => prev.filter(r => !archivedRowIds.has(r.id)));
+                setSelectedRowKeys([]);
+                setFocusedRowKey(undefined);
+                if (areArchivedDetailsLoadedRef.current)
+                    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 {
+            abortControllerRef.current = undefined;
+            setWaitPanel(CLOSED_WAIT_PANEL);
+            setIsArchiving(false);
+        }
+    };
+    // Archiviazione di una singola riga, con avanzamento dell'upload sulla barra secondaria
+    const archiveRowAsync = async (row, detailTID, dataTypeByMid, associationMids, signal) => {
+        const ae = new ArchiveEngineByID(SDK_Globals.tmSession);
+        ae.TID = detailTID;
+        ae.Metadata_ClearAll();
+        // Valori del form + associazioni con il master (le associazioni prevalgono)
+        const valueByMid = new Map();
+        for (const v of row.__values) {
+            if (v.mid !== undefined && v.value)
+                valueByMid.set(v.mid, v.value);
+        }
+        for (const a of associationMids) {
+            if (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;
+        let firstBlock = true;
+        let maxFileSize = 0;
+        return ae.ArchiveAsync(signal, (pd) => {
+            if (firstBlock) {
+                maxFileSize = pd.ProgressBarMaximum ?? 0;
+                setWaitPanel(prev => ({ ...prev, waitPanelMaxValueSecondary: maxFileSize }));
+                firstBlock = false;
+            }
+            setWaitPanel(prev => ({
+                ...prev,
+                waitPanelValueSecondary: pd.ProgressBarValue,
+                waitPanelTextSecondary: `Uploading... ${Globalization.getNumberDisplayValue(pd.ProgressBarValue, true)} / ${Globalization.getNumberDisplayValue(maxFileSize, true)}`,
+            }));
+            if (pd.ProgressBarValue === pd.ProgressBarMaximum) {
+                setWaitPanel(prev => ({ ...prev, waitPanelValueSecondary: 0, waitPanelMaxValueSecondary: 0, waitPanelTextSecondary: '' }));
+                firstBlock = true;
+            }
+        });
+    };
+    return {
+        // Flusso
+        isLoading, isSummaryReady, phase, setPhase,
+        detailRelationItems, selectedRelation, selectedItem, hasMultipleTypes,
+        selectRelation, backToTypeSelection, isBackLocked, closeModal,
+        // Sezioni
+        sectionsOpen, setSectionOpen, clearLayout, layoutResetToken,
+        // 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,
+        // Archiviazione
+        stopOnFirstError, setStopOnFirstError, isArchiving, archiveAllAsync,
+        waitPanel, abortController: abortControllerRef.current,
+    };
+};