@topconsultnpm/sdkui-react 6.22.0-dev2.2 → 6.22.0-dev2.21

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
+    };
+};

package/lib/hooks/useTMDistinctValuesSelection.d.ts

@@ -0,0 +1,42 @@
+import { LayoutModes, MetadataDescriptor } from '@topconsultnpm/sdk-ts';
+import { DataGridTypes } from 'devextreme-react/data-grid';
+import { SelectedValueItem } from '../components/choosers/TMSelectedValuesSummary';
+export type TMDistinctValuesEventArgs = {
+    tid: number | undefined;
+    mid: number | undefined;
+    newValue: string | undefined;
+    isAppendMode: boolean;
+};
+interface ITMDistinctValuesSelectionParams {
+    tid: number | undefined;
+    mid: number | undefined;
+    /** Metadato del campo: sui suoi permessi e sul suo tipo si decide cosa è selezionabile e accodabile */
+    md: MetadataDescriptor | undefined;
+    layoutMode: LayoutModes;
+    allowAppendMode: boolean;
+    separator: string;
+    /** Metadato da cui viene prelevato il valore, che nella ricerca rapida può essere diverso da `md` */
+    selectedValueMd: MetadataDescriptor | undefined;
+    /** Estrae il valore dalla riga focalizzata: le due sorgenti hanno righe di forma diversa */
+    getRowValue: (row: any) => string | undefined;
+    getMetadataDisplayValue: (columnMd: MetadataDescriptor | undefined, value: any) => any;
+    onSelectionChanged?: (e: TMDistinctValuesEventArgs) => void;
+}
+/**
+ * Selezione di TMDistinctValues: la riga focalizzata nella griglia diventa il valore del campo del form,
+ * in sostituzione di quello precedente oppure, in modalità Accoda, in aggiunta ai valori già scelti.
+ *
+ * Vale per entrambe le sorgenti del pannello: cosa leggere dalla riga viene deciso da chi lo usa.
+ */
+export declare const useTMDistinctValuesSelection: ({ tid, mid, md, layoutMode, allowAppendMode, separator, selectedValueMd, getRowValue, getMetadataDisplayValue, onSelectionChanged }: ITMDistinctValuesSelectionParams) => {
+    focusedItem: any;
+    setFocusedItem: import("react").Dispatch<any>;
+    isAppendMode: boolean;
+    isAppendVisible: boolean;
+    selectedValues: SelectedValueItem[];
+    onFocusedRowChanged: (e: DataGridTypes.FocusedRowChangedEvent) => void;
+    onAppendModeChanged: () => void;
+    onRemoveSelectedValue: (value: string) => void;
+    onClearSelectedValues: () => void;
+};
+export {};

package/lib/hooks/useTMDistinctValuesSelection.js

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { AccessLevels, LayoutModes, MetadataDataDomains, MetadataDataTypes } from '@topconsultnpm/sdk-ts';
+import { formatDateTimeByMetadataFormat, stringIsNullOrEmpty } from '../helper';
+/**
+ * Selezione di TMDistinctValues: la riga focalizzata nella griglia diventa il valore del campo del form,
+ * in sostituzione di quello precedente oppure, in modalità Accoda, in aggiunta ai valori già scelti.
+ *
+ * Vale per entrambe le sorgenti del pannello: cosa leggere dalla riga viene deciso da chi lo usa.
+ */
+export const useTMDistinctValuesSelection = ({ tid, mid, md, layoutMode, allowAppendMode, separator, selectedValueMd, getRowValue, getMetadataDisplayValue, onSelectionChanged }) => {
+    const [focusedItem, setFocusedItem] = useState();
+    const [isAppendMode, setIsAppendMode] = useState(false);
+    const [appendedValues, setAppendedValues] = useState(new Set());
+    // Cambiando metadato la selezione fatta sul precedente non ha più senso
+    useEffect(() => {
+        setIsAppendMode(false);
+        setFocusedItem(undefined);
+        setAppendedValues(new Set());
+    }, [md]);
+    // Sul metadato serve il permesso adeguato alla modalità corrente: senza, la riga focalizzata non produce alcun valore
+    const canPickValue = useMemo(() => {
+        if (!md)
+            return false;
+        if ((layoutMode === LayoutModes.Ark || layoutMode === LayoutModes.Update) && md.dataDomain === MetadataDataDomains.Computed)
+            return false;
+        switch (layoutMode) {
+            case LayoutModes.Ark: return md.perm?.canArchive === AccessLevels.Yes;
+            case LayoutModes.Update: return md.perm?.canUpdate === AccessLevels.Yes;
+            case LayoutModes.None: return md.perm?.canSearch === AccessLevels.Yes;
+            // Le altre modalità non hanno un permesso da verificare
+            default: return true;
+        }
+    }, [md, layoutMode]);
+    useEffect(() => {
+        if (!focusedItem || !canPickValue)
+            return;
+        const focusedValue = getRowValue(focusedItem);
+        if (stringIsNullOrEmpty(focusedValue)) {
+            // In accodamento una riga con valore vuoto non ha nulla da aggiungere: la selezione già fatta va conservata
+            if (isAppendMode)
+                return;
+            emitSelection(new Set());
+            return;
+        }
+        const value = md?.dataType === MetadataDataTypes.Number ? parseFloat(focusedValue.replace(',', '.')).toString() : focusedValue;
+        // Fuori dalla modalità Accoda la selezione sostituisce sempre il valore precedente
+        emitSelection(new Set(isAppendMode ? [...appendedValues, value] : [value]));
+    }, [focusedItem]);
+    // Unico punto da cui la selezione viene aggiornata e notificata al campo del form
+    const emitSelection = (values) => {
+        setAppendedValues(values);
+        onSelectionChanged?.({ tid: tid, mid: mid, newValue: values.size > 0 ? Array.from(values).join(separator) : undefined, isAppendMode: isAppendMode });
+    };
+    // Il riepilogo agisce sugli stessi valori della griglia: rimuovendone uno il campo del form va riallineato
+    const updateSelectionFromSummary = (values) => {
+        // Il prossimo click sulla riga appena rimossa deve poter riportare il valore nella selezione: senza azzerare
+        // il focus la griglia non rinotifica la riga già focalizzata
+        setFocusedItem(undefined);
+        emitSelection(values);
+    };
+    const onRemoveSelectedValue = (value) => {
+        const newAppendedValues = new Set(appendedValues);
+        newAppendedValues.delete(value);
+        updateSelectionFromSummary(newAppendedValues);
+    };
+    const onClearSelectedValues = () => updateSelectionFromSummary(new Set());
+    const onAppendModeChanged = () => {
+        const newIsAppendMode = !isAppendMode;
+        // Disattivando l'accodamento si riparte da zero: il prossimo click sostituirà il valore
+        if (!newIsAppendMode)
+            setAppendedValues(new Set());
+        setIsAppendMode(newIsAppendMode);
+    };
+    const onFocusedRowChanged = useCallback((e) => {
+        setFocusedItem(e.row?.data);
+    }, []);
+    /** L'accodamento non è proponibile dove il campo del form accetta un solo valore */
+    const isAppendVisible = useMemo(() => {
+        if (!allowAppendMode)
+            return false;
+        if (layoutMode !== LayoutModes.Ark && layoutMode !== LayoutModes.Update)
+            return true;
+        if (!md)
+            return true;
+        if (md.dataType === MetadataDataTypes.DateTime)
+            return false;
+        if (md.dataType === MetadataDataTypes.Number)
+            return false;
+        return md.dataDomain === undefined || md.dataDomain === MetadataDataDomains.None;
+    }, [allowAppendMode, layoutMode, md]);
+    /** Valori selezionati con la descrizione con cui vanno mostrati nel riepilogo */
+    const selectedValues = useMemo(() => Array.from(appendedValues).map((value) => {
+        if (selectedValueMd?.dataType === MetadataDataTypes.DateTime) {
+            const date = new Date(value);
+            return { value: value, display: Number.isNaN(date.getTime()) ? value : formatDateTimeByMetadataFormat(date, selectedValueMd?.format?.format, selectedValueMd?.format?.formatCulture) };
+        }
+        return { value: value, display: getMetadataDisplayValue(selectedValueMd, value) ?? value };
+    }), [appendedValues, selectedValueMd, getMetadataDisplayValue]);
+    return {
+        focusedItem, setFocusedItem, isAppendMode, isAppendVisible, selectedValues,
+        onFocusedRowChanged, onAppendModeChanged, onRemoveSelectedValue, onClearSelectedValues
+    };
+};

package/lib/hooks/useTMDistinctValuesSource.d.ts

@@ -0,0 +1,29 @@
+import { MetadataDescriptor } from '@topconsultnpm/sdk-ts';
+import { IColumnProps } from 'devextreme-react/data-grid';
+import { TMDistinctValuesMetadataDisplay } from './useTMDistinctValuesMetadataDisplay';
+/** Righe restituite e righe totali: il caricamento è limitato, il contatore mostra il rapporto */
+export type TMDistinctValuesCounts = {
+    returned: number;
+    found: number;
+};
+interface ITMDistinctValuesSourceParams {
+    tid: number | undefined;
+    mid: number | undefined;
+    display: TMDistinctValuesMetadataDisplay;
+}
+/**
+ * Sorgente "valori distinti" di TMDistinctValues: carica i valori del metadato con il relativo numero di
+ * documenti e ne espone righe, colonne e conteggi già pronti per la griglia.
+ *
+ * È anche la sorgente da cui viene il descrittore del metadato (`md`), usato dal pannello per permessi,
+ * titolo e visibilità dell'accodamento: per questo viene caricata anche quando è attiva la ricerca rapida.
+ */
+export declare const useTMDistinctValuesSource: ({ tid, mid, display }: ITMDistinctValuesSourceParams) => {
+    md: MetadataDescriptor | undefined;
+    dataSource: any[] | undefined;
+    counts: TMDistinctValuesCounts | undefined;
+    columns: IColumnProps[];
+    customizeColumns: (columns: Array<any>) => void;
+    loadAsync: () => Promise<void>;
+};
+export {};