@topconsultnpm/sdkui-react 6.22.0-dev2.9 → 6.22.0-t2

package/lib/hooks/useRelatedDocuments.d.ts

@@ -67,6 +67,7 @@ export interface UseRelatedDocumentsReturn {
     checkManyToManyCapability: () => Promise<void>;
     archiveRelatedDcmtHandler: (relation: RelationDescriptor, type: 'detail' | 'master') => Promise<void>;
     executeManyToManyPairing: (relation: RelationDescriptor, isPairing: boolean) => Promise<void>;
+    backToPairSearchModal: (() => void) | undefined;
 }
 export declare const useRelatedDocuments: ({ selectedSearchResult, focusedItem, currentSearchResults }: UseRelatedDocumentsProps) => UseRelatedDocumentsReturn;
 export {};

package/lib/hooks/useRelatedDocuments.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useState, useCallback, useMemo, useEffect } from 'react';
 import { SDKUI_Localizator } from '../helper/SDKUI_Localizator';
 import { IconPair, IconUnpair } from '../helper/TMIcons';
-import { hasDetailRelations, hasMasterRelations } from '../helper/dcmtsHelper';
+import { hasDetailRelations, hasMasterRelations, mapRelationAssociationsToMids } from '../helper/dcmtsHelper';
 import { SDK_Globals, SearchEngine, RelationCacheService, RelationTypes, DcmtTypeListCacheService, SystemMIDsAsNumber, AccessLevelsEx } from '@topconsultnpm/sdk-ts';
 import { TMSpinner, TMExceptionBoxManager, ShowAlert } from '../components';
 export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, currentSearchResults }) => {
@@ -28,6 +28,7 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
     const [pairSearchModalParentDID, setPairSearchModalParentDID] = useState(undefined);
     const [pairSearchModalRelation, setPairSearchModalRelation] = useState(undefined);
     const [pairSearchModalInputMids, setPairSearchModalInputMids] = useState(undefined);
+    const [pairSearchContext, setPairSearchContext] = useState(undefined);
     const [currentTIDHasDetailRelations, setCurrentTIDHasDetailRelations] = useState();
     const [currentTIDHasMasterRelations, setCurrentTIDHasMasterRelations] = useState();
     const [canArchiveMasterRelation, setCanArchiveMasterRelation] = useState(false);
@@ -86,6 +87,7 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
             if (!tms)
                 return;
             const se = new SearchEngine(tms);
+            const operationTitle = isPairing ? SDKUI_Localizator.MatchManyDocumentsManyToMany : SDKUI_Localizator.UnmatchManyDocumentsManyToMany;
             try {
                 TMSpinner.show({ description: isPairing ? 'Abbinamento in corso...' : 'Disabbinamento in corso...' });
                 for (const doc of selected) {
@@ -115,10 +117,16 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
                     }
                 }
                 onCloseModal();
+                ShowAlert({
+                    message: SDKUI_Localizator.OperationSuccess,
+                    mode: 'success',
+                    title: operationTitle,
+                    duration: 3000
+                });
             }
             catch (error) {
                 console.error('Error in onClick:', error);
-                TMExceptionBoxManager.show({ exception: error });
+                TMExceptionBoxManager.show({ title: operationTitle, exception: error });
             }
             finally {
                 TMSpinner.hide();
@@ -129,6 +137,14 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
     }), []);
     const pairFloatingActionConfig = useMemo(() => createPairFloatingActionConfig(selectedManyToManyRelation, focusedItem?.TID ? Number(focusedItem.TID) : undefined, focusedItem?.DID ? Number(focusedItem.DID) : undefined, isPairingManyToMany, () => setShowPairDcmtsModal(false)), [createPairFloatingActionConfig, selectedManyToManyRelation, focusedItem, isPairingManyToMany]);
     const pairSearchModalFloatingActionConfig = useMemo(() => createPairFloatingActionConfig(pairSearchModalRelation, pairSearchModalParentTID, pairSearchModalParentDID, true, () => setShowPairSearchModal(false)), [createPairFloatingActionConfig, pairSearchModalRelation, pairSearchModalParentTID, pairSearchModalParentDID]);
+    const backToPairSearchModal = useMemo(() => {
+        if (!pairSearchContext)
+            return undefined;
+        return () => {
+            setShowPairDcmtsModal(false);
+            openPairSearchModal(pairSearchContext.relation, pairSearchContext.targetTID, pairSearchContext.qd);
+        };
+    }, [pairSearchContext, openPairSearchModal]);
     const getAllRelationsAsync = async () => {
         const tmSession = SDK_Globals.tmSession;
         try {
@@ -224,31 +240,7 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
     };
     //This ensures archive master/detail works correctly regardless of output metadata configuration.
     const mapAssociationsToMidsAsync = useCallback(async (relation, type) => {
-        if (!relation.associations || relation.associations.length === 0)
-            return [];
-        if (!focusedItem?.TID || !focusedItem?.DID)
-            return [];
-        const searchEngine = SDK_Globals.tmSession?.NewSearchEngine();
-        if (!searchEngine)
-            return [];
-        const allMetadata = await searchEngine.GetMetadataAsync(focusedItem.TID, focusedItem.DID, false);
-        if (!allMetadata?.dtdResult?.rows?.[0] || !allMetadata.selectMIDs)
-            return [];
-        const row = allMetadata.dtdResult.rows[0];
-        const mids = allMetadata.selectMIDs;
-        const metadataMap = new Map();
-        mids.forEach((mid, index) => {
-            const value = row[index];
-            if (value !== undefined && value !== null) {
-                metadataMap.set(mid, value.toString());
-            }
-        });
-        return relation.associations.map(assoc => {
-            const sourceMid = type === 'detail' ? (assoc.item1 ?? 0) : (assoc.item2 ?? 0);
-            const targetMid = type === 'detail' ? (assoc.item2 ?? 0) : (assoc.item1 ?? 0);
-            const value = metadataMap.get(sourceMid) ?? '';
-            return { mid: targetMid, value };
-        });
+        return mapRelationAssociationsToMids(relation, type, focusedItem);
     }, [focusedItem]);
     const archiveRelatedDcmtHandler = useCallback(async (relation, type) => {
         const targetTID = type === 'detail' ? relation.detailTID : relation.masterTID;
@@ -537,6 +529,7 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
                 dcmtsReturned: pairedDocumentsResult.dtdResult.rows.length,
                 dcmtsFound: pairedDocumentsResult.dtdResult.rows.length
             };
+            setPairSearchContext(undefined);
             setPairedSearchResults([pairedSq]);
             setIsPairingManyToMany(isPairing);
             setShowPairDcmtsModal(true);
@@ -578,6 +571,7 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
             openPairSearchModal(relation, targetTID, qd);
             return;
         }
+        setPairSearchContext({ relation, targetTID, qd });
         setPairedSearchResults([filteredSq]);
         setIsPairingManyToMany(isPairing);
         setShowPairDcmtsModal(true);
@@ -652,6 +646,7 @@ export const useRelatedDocuments = ({ selectedSearchResult, focusedItem, current
         selectedManyToManyRelation,
         showManyToManyChooser,
         manyToManyChooserDataSource,
+        backToPairSearchModal,
         showPairSearchModal,
         pairSearchModalTargetTID,
         pairSearchModalParentTID,

package/lib/hooks/useShowDossiersV5.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Impostazione avanzata "Mostra pratiche V5": le pratiche (i dossier) sono
+ * sostituite dal CaseFlow e restano nascoste finché l'utente non le riattiva.
+ *
+ * Il valore vive in `SDKUI_Globals.userSettings.advancedSettings`, quindi la
+ * persistenza è quella delle altre impostazioni utente (per archivio e utente).
+ */
+export declare const SHOW_DOSSIERS_V5_CHANGED_EVENT = "showDossiersV5Changed";
+export declare const getShowDossiersV5: () => boolean;
+export declare const setShowDossiersV5: (value: boolean) => void;
+/** Legge l'impostazione e si aggiorna quando cambia. */
+export declare const useShowDossiersV5: () => boolean;

package/lib/hooks/useShowDossiersV5.js

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react';
+import { SDK_Globals } from '@topconsultnpm/sdk-ts';
+import { SDKUI_Globals } from '../helper';
+/**
+ * Impostazione avanzata "Mostra pratiche V5": le pratiche (i dossier) sono
+ * sostituite dal CaseFlow e restano nascoste finché l'utente non le riattiva.
+ *
+ * Il valore vive in `SDKUI_Globals.userSettings.advancedSettings`, quindi la
+ * persistenza è quella delle altre impostazioni utente (per archivio e utente).
+ */
+export const SHOW_DOSSIERS_V5_CHANGED_EVENT = 'showDossiersV5Changed';
+export const getShowDossiersV5 = () => {
+    return SDKUI_Globals.userSettings.advancedSettings?.showDossiersV5 === 1;
+};
+export const setShowDossiersV5 = (value) => {
+    SDKUI_Globals.userSettings.advancedSettings.showDossiersV5 = value ? 1 : 0;
+    // Il setter di AdvancedSettings emette l'evento, ma dopo un ricaricamento
+    // della pagina `advancedSettings` torna da localStorage come oggetto
+    // semplice e non lo emette più: lo lanciamo anche qui, così i consumatori
+    // non dipendono da quale delle due forme è in memoria.
+    globalThis.dispatchEvent(new CustomEvent(SHOW_DOSSIERS_V5_CHANGED_EVENT, { detail: value }));
+};
+/** Legge l'impostazione e si aggiorna quando cambia. */
+export const useShowDossiersV5 = () => {
+    const sessionDescr = SDK_Globals.tmSession?.SessionDescr;
+    const archiveId = sessionDescr?.archiveID;
+    const userId = sessionDescr?.userID;
+    const [showDossiersV5, setValue] = useState(getShowDossiersV5);
+    // Le impostazioni sono per utente e archivio: al cambio sessione va riletto.
+    useEffect(() => { setValue(getShowDossiersV5()); }, [archiveId, userId]);
+    useEffect(() => {
+        const onChanged = () => setValue(getShowDossiersV5());
+        globalThis.addEventListener(SHOW_DOSSIERS_V5_CHANGED_EVENT, onChanged);
+        return () => globalThis.removeEventListener(SHOW_DOSSIERS_V5_CHANGED_EVENT, onChanged);
+    }, []);
+    return showDossiersV5;
+};

package/lib/hooks/useTMDistinctValuesMetadataDisplay.d.ts

@@ -0,0 +1,18 @@
+import { MetadataDescriptor } from '@topconsultnpm/sdk-ts';
+import { IColumnProps } from 'devextreme-react/data-grid';
+export declare const needsDisplayValue: (columnMd: MetadataDescriptor | undefined) => boolean;
+/**
+ * Resa dei valori nelle griglie di TMDistinctValues: al posto della chiave archiviata mostra la descrizione
+ * presa dalle cache di liste dati e utenti, tenendole allineate alle colonne effettivamente visualizzate.
+ *
+ * Vale per entrambe le sorgenti del pannello (valori distinti e ricerca rapida, che può essere su un altro
+ * tipo documento): le chiavi delle due sorgenti vengono accumulate e ricaricate sempre insieme, altrimenti
+ * un caricamento farebbe perdere le descrizioni dell'altra sorgente.
+ */
+export declare const useTMDistinctValuesMetadataDisplay: () => {
+    loadDisplayCachesAsync: (columnsMd: Array<MetadataDescriptor | undefined>, rows: string[][] | undefined) => Promise<void>;
+    getMetadataDisplayValue: (columnMd: MetadataDescriptor | undefined, value: any) => any;
+    displayValueColumnProps: (columnMd: MetadataDescriptor | undefined, dataField: string) => Partial<IColumnProps>;
+};
+/** Tipo di ritorno dell'hook: le sorgenti di TMDistinctValues lo ricevono come dipendenza */
+export type TMDistinctValuesMetadataDisplay = ReturnType<typeof useTMDistinctValuesMetadataDisplay>;

package/lib/hooks/useTMDistinctValuesMetadataDisplay.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useRef } from 'react';
+import { DataListViewModes, MetadataDataDomains } from '@topconsultnpm/sdk-ts';
+import { SDKUI_Localizator, stringIsNullOrEmpty } from '../helper';
+import { useDataListItem } from './useDataListItem';
+import { useDataUserIdItem } from './useDataUserIdItem';
+// Le griglie di TMDistinctValues mostrano la descrizione, non la chiave archiviata (es. TD01 -> FATTURA)
+export const needsDisplayValue = (columnMd) => columnMd?.dataDomain === MetadataDataDomains.DataList || columnMd?.dataDomain === MetadataDataDomains.UserID;
+const getCellDataListViewMode = (columnMd) => columnMd?.dataListViewMode === DataListViewModes.Description
+    ? DataListViewModes.Description
+    : DataListViewModes.ImageAndDescription;
+/**
+ * Resa dei valori nelle griglie di TMDistinctValues: al posto della chiave archiviata mostra la descrizione
+ * presa dalle cache di liste dati e utenti, tenendole allineate alle colonne effettivamente visualizzate.
+ *
+ * Vale per entrambe le sorgenti del pannello (valori distinti e ricerca rapida, che può essere su un altro
+ * tipo documento): le chiavi delle due sorgenti vengono accumulate e ricaricate sempre insieme, altrimenti
+ * un caricamento farebbe perdere le descrizioni dell'altra sorgente.
+ */
+export const useTMDistinctValuesMetadataDisplay = () => {
+    const { loadDataListsAsync, renderDataListCell, getDataListItem, hasDataList } = useDataListItem();
+    const { loadUsersAsync, renderUserIdViewer, getUserItem, getCompleteUserName, hasUser } = useDataUserIdItem();
+    // Le cache vengono sostituite con le sole chiavi richieste a ogni caricamento: qui si accumula l'insieme completo
+    const requestedDataListIDsRef = useRef(new Set());
+    const requestedUserIDsRef = useRef(new Set());
+    // I caricamenti delle due sorgenti possono sovrapporsi: la coda garantisce che l'ultimo a scrivere nelle cache sia quello con l'insieme completo di chiavi
+    const displayCachesQueueRef = useRef(Promise.resolve());
+    /** Le descrizioni vengono dalle cache di liste dati e utenti: vanno caricate prima di mostrare le righe */
+    const loadDisplayCachesAsync = useCallback(async (columnsMd, rows) => {
+        const dataListIDs = new Set();
+        const userIDs = new Set();
+        columnsMd.forEach((columnMd, index) => {
+            if (columnMd?.dataDomain === MetadataDataDomains.DataList && columnMd.dataListID) {
+                dataListIDs.add(columnMd.dataListID);
+                return;
+            }
+            if (columnMd?.dataDomain !== MetadataDataDomains.UserID)
+                return;
+            // Della cache utenti serve solo chi compare effettivamente nelle righe
+            rows?.forEach((row) => {
+                const userId = Number(row[index]);
+                if (userId && userId > 0)
+                    userIDs.add(userId);
+            });
+        });
+        if (dataListIDs.size <= 0 && userIDs.size <= 0)
+            return;
+        // In coda al caricamento precedente: l'insieme delle chiavi va calcolato quando è il turno di questa richiesta
+        const load = displayCachesQueueRef.current.then(async () => {
+            // Se tutte le chiavi richieste sono già in cache non c'è nulla da ricaricare
+            const isCacheComplete = Array.from(dataListIDs).every(id => hasDataList(id)) && Array.from(userIDs).every(id => hasUser(id));
+            if (isCacheComplete)
+                return;
+            dataListIDs.forEach(id => requestedDataListIDsRef.current.add(id));
+            userIDs.forEach(id => requestedUserIDsRef.current.add(id));
+            // Ricaricate tutte insieme: il caricamento sostituisce il contenuto delle cache
+            if (requestedDataListIDsRef.current.size > 0)
+                await loadDataListsAsync(new Set(requestedDataListIDsRef.current));
+            if (requestedUserIDsRef.current.size > 0)
+                await loadUsersAsync(new Set(requestedUserIDsRef.current));
+        });
+        // La coda non deve interrompersi per un caricamento fallito
+        displayCachesQueueRef.current = load.catch(() => { });
+        await load;
+    }, [loadDataListsAsync, loadUsersAsync, hasDataList, hasUser]);
+    const renderMetadataCell = useCallback((columnMd, cellData) => {
+        if (!cellData || cellData.value === undefined)
+            return null;
+        if (columnMd?.dataDomain === MetadataDataDomains.DataList && columnMd.dataListID) {
+            return renderDataListCell(cellData.value, columnMd.dataListID, getCellDataListViewMode(columnMd));
+        }
+        if (columnMd?.dataDomain === MetadataDataDomains.UserID) {
+            return renderUserIdViewer(Number(cellData.value), true);
+        }
+        return _jsx("div", { children: cellData.text });
+    }, [renderDataListCell, renderUserIdViewer]);
+    /** Descrizione da mostrare al posto della chiave archiviata, fuori dal contesto di una cella di griglia */
+    const getMetadataDisplayValue = useCallback((columnMd, value) => {
+        if (stringIsNullOrEmpty(value))
+            return value;
+        if (columnMd?.dataDomain === MetadataDataDomains.DataList && columnMd.dataListID) {
+            return getDataListItem(columnMd.dataListID, value)?.name ?? value;
+        }
+        if (columnMd?.dataDomain === MetadataDataDomains.UserID) {
+            const userId = Number(value);
+            if (userId === 0)
+                return SDKUI_Localizator.SystemUser;
+            const ud = getUserItem(userId);
+            return ud ? getCompleteUserName(ud.domain, ud.name) ?? value : value;
+        }
+        return value;
+    }, [getDataListItem, getUserItem, getCompleteUserName]);
+    /** Proprietà con cui una colonna mostra la descrizione al posto della chiave archiviata: vuote per i domini che non ne hanno bisogno */
+    const displayValueColumnProps = useCallback((columnMd, dataField) => {
+        if (!needsDisplayValue(columnMd))
+            return {};
+        return {
+            cellRender: (cellData) => renderMetadataCell(columnMd, cellData),
+            calculateDisplayValue: (rowData) => getMetadataDisplayValue(columnMd, rowData?.[dataField]),
+        };
+    }, [renderMetadataCell, getMetadataDisplayValue]);
+    return { loadDisplayCachesAsync, getMetadataDisplayValue, displayValueColumnProps };
+};

package/lib/hooks/useTMDistinctValuesQuickSearch.d.ts

@@ -0,0 +1,49 @@
+import { MetadataDescriptor } from '@topconsultnpm/sdk-ts';
+import { IColumnProps } from 'devextreme-react/data-grid';
+import { DistinctValuesQuickSearchSettings } from '../helper';
+import { TMDistinctValuesCounts } from './useTMDistinctValuesSource';
+import { TMDistinctValuesMetadataDisplay } from './useTMDistinctValuesMetadataDisplay';
+/** Le due sorgenti da cui TMDistinctValues può prelevare il valore del campo */
+export declare enum DistinctValuesModes {
+    DistinctValues = 0,
+    QuickSearch = 1
+}
+/** Classe applicata alla colonna del metadato configurato nella ricerca rapida: è quella da cui si prende il valore */
+export declare const QUICK_SEARCH_VALUE_COLUMN_CLASS = "tm-quick-search-value-column";
+interface ITMDistinctValuesQuickSearchParams {
+    tid: number | undefined;
+    mid: number | undefined;
+    /** Metadato del campo, dalla sorgente dei valori distinti: è il ripiego quando la ricerca rapida non è attiva */
+    md: MetadataDescriptor | undefined;
+    display: TMDistinctValuesMetadataDisplay;
+}
+/**
+ * Sorgente "ricerca rapida" di TMDistinctValues, con il selettore di modalità del pannello: la modalità esiste
+ * solo perché esiste questa sorgente, quindi le due cose vivono insieme.
+ *
+ * La ricerca rapida non filtra i valori distinti: è una sorgente alternativa da cui prelevare il valore del
+ * metadato configurato nelle impostazioni, che restano associate alla coppia (tid, mid).
+ */
+export declare const useTMDistinctValuesQuickSearch: ({ tid, mid, md, display }: ITMDistinctValuesQuickSearchParams) => {
+    mode: DistinctValuesModes;
+    isQuickSearchMode: boolean;
+    isQuickSearchGridVisible: boolean;
+    isFirstSearchPending: boolean;
+    settings: DistinctValuesQuickSearchSettings | undefined;
+    columns: IColumnProps[];
+    dataSource: any[];
+    counts: TMDistinctValuesCounts;
+    customizeColumns: (columns: Array<any>) => void;
+    valueField: string | undefined;
+    selectedValueMd: MetadataDescriptor | undefined;
+    showSettingsForm: boolean;
+    setShowSettingsForm: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    onModeChanged: (newMode: DistinctValuesModes) => void;
+    onSaveSettings: (newSettings: DistinctValuesQuickSearchSettings) => void;
+    onDeleteSettings: () => void;
+    onDeleteSettingsClick: () => void;
+    onSettingsFormClose: () => void;
+    refreshAsync: () => Promise<void>;
+    ConfirmQueryParamsDialog: () => JSX.Element;
+};
+export {};

package/lib/hooks/useTMDistinctValuesQuickSearch.js

@@ -0,0 +1,307 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { DataColumnTypes, DcmtTypeListCacheService, SavedQueryCacheService, SDK_Globals, SDK_Localizator, SearchEngine, SelectItemVisibilities, SystemMIDsAsNumber } from '@topconsultnpm/sdk-ts';
+import { customizeSearchByDisplayText, generateUniqueColumnKeys, getColumnFormatInfo, getDateDisplayText, getDistinctValuesQuickSearch, getSysAllDcmtsSQD, IsParametricQuery, prepareQdForSearchAsync, removeDistinctValuesQuickSearch, saveDistinctValuesQuickSearch, searchResultDescriptorToSimpleArray, SDKUI_Localizator, stringIsNullOrEmpty, SYS_ALL_DCMTS_SQD_ID } from '../helper';
+import ShowAlert from '../components/base/TMAlert';
+import { ButtonNames, TMExceptionBoxManager, TMMessageBoxManager } from '../components/base/TMPopUp';
+import TMSpinner from '../components/base/TMSpinner';
+import { getColumnMid, getDateDisplayFormat, getMetadataName, toGridDataType, withRowIndex } from './tmDistinctValuesGridHelper';
+import { needsDisplayValue } from './useTMDistinctValuesMetadataDisplay';
+import { useQueryParametersDialog } from './useQueryParametersDialog';
+/** Le due sorgenti da cui TMDistinctValues può prelevare il valore del campo */
+export var DistinctValuesModes;
+(function (DistinctValuesModes) {
+    DistinctValuesModes[DistinctValuesModes["DistinctValues"] = 0] = "DistinctValues";
+    DistinctValuesModes[DistinctValuesModes["QuickSearch"] = 1] = "QuickSearch";
+})(DistinctValuesModes || (DistinctValuesModes = {}));
+/** Classe applicata alla colonna del metadato configurato nella ricerca rapida: è quella da cui si prende il valore */
+export const QUICK_SEARCH_VALUE_COLUMN_CLASS = 'tm-quick-search-value-column';
+// Sostituisce i segnaposto dei parametri con i valori confermati dall'utente
+const applyQueryParams = (qd, qdParams) => {
+    for (const qpd of qdParams) {
+        const value = !qpd.value ? '' : qpd.value.toString();
+        let wi = qd.where?.find(o => o.value1 === qpd.name);
+        if (wi) {
+            wi.value1 = value;
+            continue;
+        }
+        wi = qd.where?.find(o => o.value2 === qpd.name);
+        if (wi)
+            wi.value2 = value;
+    }
+};
+/**
+ * Sorgente "ricerca rapida" di TMDistinctValues, con il selettore di modalità del pannello: la modalità esiste
+ * solo perché esiste questa sorgente, quindi le due cose vivono insieme.
+ *
+ * La ricerca rapida non filtra i valori distinti: è una sorgente alternativa da cui prelevare il valore del
+ * metadato configurato nelle impostazioni, che restano associate alla coppia (tid, mid).
+ */
+export const useTMDistinctValuesQuickSearch = ({ tid, mid, md, display }) => {
+    const { loadDisplayCachesAsync, displayValueColumnProps, getMetadataDisplayValue } = display;
+    // L'impostazione configurata per il campo va letta già al primo render: leggerla solo nell'effect farebbe nascere
+    // il pannello nella modalità dei valori distinti, per poi passare alla ricerca rapida sotto gli occhi dell'utente
+    const savedSettings = getDistinctValuesQuickSearch(tid, mid);
+    const [mode, setMode] = useState(savedSettings ? DistinctValuesModes.QuickSearch : DistinctValuesModes.DistinctValues);
+    const [settings, setSettings] = useState(savedSettings);
+    const [showSettingsForm, setShowSettingsForm] = useState(false);
+    const [result, setResult] = useState();
+    // Metadato di ciascuna colonna del risultato, nello stesso ordine delle colonne
+    const [columnsMd, setColumnsMd] = useState([]);
+    // Impostazione per cui la ricerca è già stata portata a termine, con o senza risultato: finché non coincide con
+    // quella corrente il risultato non è ancora noto, e con esso le colonne da cui dipende la larghezza del pannello
+    const [completedSettings, setCompletedSettings] = useState();
+    const [confirmQueryParams, ConfirmQueryParamsDialog] = useQueryParametersDialog();
+    // Identifica la richiesta corrente: dopo ogni await le risposte delle richieste obsolete vengono scartate
+    const requestIdRef = useRef(0);
+    // Ultimi parametri confermati: vengono riproposti alla successiva esecuzione della stessa ricerca
+    const lastQdParamsRef = useRef([]);
+    const isQuickSearchMode = mode === DistinctValuesModes.QuickSearch;
+    // Finché l'impostazione non è stata salvata restano visibili i valori distinti: la griglia della ricerca rapida sarebbe vuota
+    const isQuickSearchGridVisible = isQuickSearchMode && !!settings;
+    /** La prima ricerca per l'impostazione corrente non è ancora conclusa: le colonne del risultato non sono note */
+    const isFirstSearchPending = isQuickSearchGridVisible && completedSettings !== settings;
+    // Cambiando campo va ripresa l'impostazione configurata per la nuova coppia (tid, mid)
+    useEffect(() => {
+        const fieldQuickSearch = getDistinctValuesQuickSearch(tid, mid);
+        setSettings(fieldQuickSearch);
+        // Se il campo ha una ricerca rapida configurata è quella la sorgente da mostrare, non i valori distinti
+        setMode(fieldQuickSearch ? DistinctValuesModes.QuickSearch : DistinctValuesModes.DistinctValues);
+        setResult(undefined);
+        setColumnsMd([]);
+        setCompletedSettings(undefined);
+        lastQdParamsRef.current = [];
+    }, [tid, mid]);
+    // I valori distinti restano in memoria dopo il primo caricamento, la ricerca rapida va eseguita a ogni cambio di impostazione
+    useEffect(() => {
+        if (!isQuickSearchMode || !settings)
+            return;
+        runAsync(settings);
+    }, [mode, settings]);
+    const runAsync = async (currentSettings) => {
+        // Impostazione incompleta: non c'è nulla da eseguire, ma il pannello non deve restare in attesa del risultato
+        if (!currentSettings.tid || !currentSettings.sqdId) {
+            setCompletedSettings(currentSettings);
+            return;
+        }
+        const requestId = ++requestIdRef.current;
+        const isStale = () => requestId !== requestIdRef.current;
+        setResult(undefined);
+        setColumnsMd([]);
+        try {
+            const sqd = currentSettings.sqdId === SYS_ALL_DCMTS_SQD_ID
+                ? await getSysAllDcmtsSQD(currentSettings.tid, false)
+                : await SavedQueryCacheService.GetAsync(currentSettings.sqdId);
+            const qd = SearchEngine.NormalizeQueryDescriptor(sqd?.qd);
+            if (!qd) {
+                // La ricerca salvata può essere stata eliminata o non essere più accessibile: senza avviso il pannello resterebbe vuoto senza spiegazione
+                if (isStale())
+                    return;
+                ShowAlert({ mode: 'warning', title: SDK_Localizator.SavedQuery, message: 'La ricerca rapida configurata non è più disponibile: modificare le impostazioni', duration: 4000 });
+                return;
+            }
+            const qdSearch = await prepareQdForSearchAsync(qd, sqd?.isEasyWhere === 1);
+            qdSearch.maxDcmtsToBeReturned = currentSettings.maxDcmtsToBeReturned;
+            qdSearch.select?.forEach(o => { o.visibility ??= SelectItemVisibilities.Visible; });
+            // Una ricerca parametrica non è eseguibile senza i valori dei parametri: vengono chiesti all'utente
+            if (IsParametricQuery(qdSearch)) {
+                const qdParams = await confirmQueryParams(qdSearch, lastQdParamsRef.current);
+                if (!qdParams || qdParams.length <= 0)
+                    return;
+                lastQdParamsRef.current = qdParams;
+                applyQueryParams(qdSearch, qdParams);
+            }
+            TMSpinner.show({ description: `${SDKUI_Localizator.Search} ...` });
+            const searchResult = await SDK_Globals.tmSession?.NewSearchEngine().SearchByIDAsync(qdSearch);
+            if (isStale())
+                return;
+            if ((searchResult?.dcmtsFound ?? 0) <= 0)
+                ShowAlert({ mode: 'warning', title: SDKUI_Localizator.SearchResult, message: SDKUI_Localizator.NoDcmtFound, duration: 3000 });
+            const resultColumnsMd = await loadColumnsMdAsync(currentSettings.tid, searchResult);
+            if (isStale())
+                return;
+            setColumnsMd(resultColumnsMd);
+            setResult(searchResult);
+        }
+        catch (e) {
+            if (isStale())
+                return;
+            TMExceptionBoxManager.show({ exception: e });
+        }
+        finally {
+            TMSpinner.hide();
+            // Anche senza risultato la ricerca è conclusa: il pannello va mostrato, è da lì che si correggono le impostazioni
+            if (!isStale())
+                setCompletedSettings(currentSettings);
+        }
+    };
+    // Risolve ogni colonna del risultato nel proprio metadato e carica le cache (liste dati, utenti) necessarie a mostrarne la descrizione
+    const loadColumnsMdAsync = async (searchTid, searchResult) => {
+        const columns = searchResult?.dtdResult?.columns ?? [];
+        if (columns.length <= 0)
+            return [];
+        const dtd = await DcmtTypeListCacheService.GetAsync(searchTid, true);
+        const resultColumnsMd = columns.map((col, index) => dtd?.metadata?.find(o => o.id === getColumnMid(col, searchResult?.selectMIDs, index)));
+        await loadDisplayCachesAsync(resultColumnsMd, searchResult?.dtdResult?.rows);
+        return resultColumnsMd;
+    };
+    const refreshAsync = async () => { if (settings)
+        await runAsync(settings); };
+    const columnKeys = useMemo(() => generateUniqueColumnKeys(result?.dtdResult?.columns, result?.fromTID), [result]);
+    /** Individua il campo della griglia corrispondente a un metadato del risultato */
+    const findField = useCallback((targetMid) => {
+        const columns = result?.dtdResult?.columns;
+        if (!columns || !targetMid)
+            return undefined;
+        let columnIndex = columns.findIndex(col => Number(col.extendedProperties?.['MID'] ?? 0) === targetMid);
+        // Senza le proprietà estese resta l'allineamento posizionale tra selectMIDs e colonne del risultato
+        if (columnIndex < 0)
+            columnIndex = result?.selectMIDs?.indexOf(targetMid) ?? -1;
+        return columnIndex >= 0 ? columnKeys[columnIndex] : undefined;
+    }, [result, columnKeys]);
+    // Righe dalla più recente alla meno recente: conta la data di ultima modifica, in mancanza quella di creazione
+    const dataSource = useMemo(() => {
+        const rows = searchResultDescriptorToSimpleArray(result) ?? [];
+        const lastUpdateField = findField(SystemMIDsAsNumber.LastUpdateTime);
+        const creationField = findField(SystemMIDsAsNumber.CreationTime);
+        if (!lastUpdateField && !creationField)
+            return rows;
+        const getRowTime = (item) => {
+            const value = (lastUpdateField ? item?.[lastUpdateField] : undefined) || (creationField ? item?.[creationField] : undefined);
+            if (stringIsNullOrEmpty(value))
+                return undefined;
+            const time = new Date(value).getTime();
+            return Number.isNaN(time) ? undefined : time;
+        };
+        rows.sort((a, b) => {
+            const timeA = getRowTime(a);
+            const timeB = getRowTime(b);
+            // Le righe prive di entrambe le date finiscono in fondo, nel loro ordine originale
+            if (timeA === undefined)
+                return timeB === undefined ? 0 : 1;
+            if (timeB === undefined)
+                return -1;
+            return timeB - timeA;
+        });
+        return withRowIndex(rows);
+    }, [result, findField]);
+    /** Il valore da riportare nel campo è quello della colonna del metadato configurato nelle impostazioni */
+    const valueField = useMemo(() => findField(settings?.mid), [findField, settings?.mid]);
+    /** Metadato da cui viene prelevato il valore: nel riepilogo serve per mostrarne la descrizione al posto della chiave archiviata */
+    const selectedValueMd = useMemo(() => {
+        if (!isQuickSearchGridVisible)
+            return md;
+        const columnIndex = valueField ? columnKeys.indexOf(valueField) : -1;
+        return columnIndex >= 0 ? columnsMd[columnIndex] : undefined;
+    }, [isQuickSearchGridVisible, md, valueField, columnKeys, columnsMd]);
+    const columns = useMemo(() => {
+        const resultColumns = result?.dtdResult?.columns?.map((col, index) => {
+            const columnMd = columnsMd[index];
+            const dataField = columnKeys[index];
+            // È la colonna da cui viene prelevato il valore: va sempre in evidenza e non può restare nascosta
+            const isValueColumn = !!valueField && dataField === valueField;
+            // Formato e cultura di visualizzazione definiti sulle proprietà estese della colonna
+            const { format, formatCulture } = getColumnFormatInfo(col);
+            // Il MID risolve l'intestazione quando la didascalia del risultato è assente
+            const columnMid = getColumnMid(col, result?.selectMIDs, index);
+            return {
+                dataField: dataField,
+                // Nell'intestazione va il nome del metadato: la didascalia del risultato può essere assente e lascerebbe la colonna senza nome
+                caption: getMetadataName(columnMd) ?? col.caption ?? (columnMid ? `MID ${columnMid}` : undefined),
+                // I metadati di sistema aggiunti alla query restano nel risultato ma non vanno mostrati
+                visible: isValueColumn || col.extendedProperties?.['Visibility'] !== 'Hidden',
+                // Dalla selezione colonne non deve essere possibile nascondere la colonna del valore
+                allowHiding: !isValueColumn,
+                cssClass: isValueColumn ? QUICK_SEARCH_VALUE_COLUMN_CLASS : undefined,
+                dataType: toGridDataType(col.dataType),
+                format: col.dataType === DataColumnTypes.DateTime ? getDateDisplayFormat(format, formatCulture) : '',
+                ...displayValueColumnProps(columnMd, dataField)
+            };
+        }) ?? [];
+        // La colonna del metadato configurato va in testa: è quella da cui si preleva il valore
+        const valueColumnIndex = valueField ? resultColumns.findIndex(col => col.dataField === valueField) : -1;
+        if (valueColumnIndex > 0) {
+            const [valueColumn] = resultColumns.splice(valueColumnIndex, 1);
+            resultColumns.unshift(valueColumn);
+        }
+        return resultColumns;
+    }, [result, columnKeys, columnsMd, valueField, displayValueColumnProps]);
+    // Date formattate e descrizioni di liste dati/utenti: la ricerca va fatta sul testo mostrato, non sul valore archiviato
+    const searchTextGetters = useMemo(() => {
+        const getters = new Map();
+        result?.dtdResult?.columns?.forEach((col, index) => {
+            const dataField = columnKeys[index];
+            if (!dataField)
+                return;
+            if (col.dataType === DataColumnTypes.DateTime) {
+                const { format, formatCulture } = getColumnFormatInfo(col);
+                getters.set(dataField, (rowData) => getDateDisplayText(rowData?.[dataField], format, formatCulture));
+                return;
+            }
+            const columnMd = columnsMd[index];
+            if (needsDisplayValue(columnMd)) {
+                getters.set(dataField, (rowData) => String(getMetadataDisplayValue(columnMd, rowData?.[dataField]) ?? ''));
+            }
+        });
+        return getters;
+    }, [result, columnKeys, columnsMd, getMetadataDisplayValue]);
+    const customizeColumns = useMemo(() => customizeSearchByDisplayText(searchTextGetters), [searchTextGetters]);
+    const counts = useMemo(() => ({ returned: result?.dcmtsReturned ?? 0, found: result?.dcmtsFound ?? 0 }), [result]);
+    // Senza la colonna del metadato configurato la selezione di una riga non produrrebbe alcun valore
+    useEffect(() => {
+        if (!isQuickSearchGridVisible)
+            return;
+        if (isFirstSearchPending)
+            return;
+        if (!result?.dtdResult?.rows?.length)
+            return;
+        if (valueField)
+            return;
+        ShowAlert({ mode: 'warning', title: SDK_Localizator.SavedQuery, message: 'La ricerca rapida selezionata non restituisce il metadato configurato', duration: 4000 });
+    }, [isQuickSearchGridVisible, isFirstSearchPending, result, valueField]);
+    const onModeChanged = (newMode) => {
+        setMode(newMode);
+        // Senza impostazione salvata la ricerca rapida non è utilizzabile: si chiede subito come configurarla
+        if (newMode === DistinctValuesModes.QuickSearch && !settings)
+            setShowSettingsForm(true);
+    };
+    const onSaveSettings = (newSettings) => {
+        // L'impostazione resta configurata per il campo: viene ripresa alla prossima apertura del pannello
+        saveDistinctValuesQuickSearch(tid, mid, newSettings);
+        // I parametri della ricerca precedente non valgono per la nuova ricerca
+        lastQdParamsRef.current = [];
+        setSettings(newSettings);
+        setShowSettingsForm(false);
+    };
+    const onDeleteSettings = () => {
+        removeDistinctValuesQuickSearch(tid, mid);
+        lastQdParamsRef.current = [];
+        setSettings(undefined);
+        setResult(undefined);
+        setColumnsMd([]);
+        setShowSettingsForm(false);
+        // Senza impostazione la ricerca rapida non è utilizzabile: si torna ai valori distinti
+        setMode(DistinctValuesModes.DistinctValues);
+    };
+    const onDeleteSettingsClick = () => {
+        TMMessageBoxManager.show({
+            title: SDKUI_Localizator.Delete,
+            message: SDKUI_Localizator.QuickSearchSettings_DeleteConfirmFor1.replaceParams(getMetadataName(md) ?? SDK_Localizator.Metadata),
+            buttons: [ButtonNames.YES, ButtonNames.NO],
+            onButtonClick: (e) => { if (e === ButtonNames.YES)
+                onDeleteSettings(); }
+        });
+    };
+    const onSettingsFormClose = () => {
+        setShowSettingsForm(false);
+        // Senza impostazione la ricerca rapida non è utilizzabile: si torna ai valori distinti
+        if (!settings)
+            setMode(DistinctValuesModes.DistinctValues);
+    };
+    return {
+        mode, isQuickSearchMode, isQuickSearchGridVisible, isFirstSearchPending,
+        settings, columns, dataSource, counts, customizeColumns, valueField, selectedValueMd,
+        showSettingsForm, setShowSettingsForm,
+        onModeChanged, onSaveSettings, onDeleteSettings, onDeleteSettingsClick, onSettingsFormClose,
+        refreshAsync, ConfirmQueryParamsDialog
+    };
+};