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

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

package/lib/hooks/useTMDistinctValuesSource.js

@@ -0,0 +1,105 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { DataColumnTypes, DcmtTypeListCacheService, MetadataDataTypes, SDK_Globals } from '@topconsultnpm/sdk-ts';
+import { TMExceptionBoxManager } from '../components/base/TMPopUp';
+import TMSpinner from '../components/base/TMSpinner';
+import { customizeSearchByDisplayText, getDateDisplayText } from '../helper';
+import { getDateDisplayFormat, withRowIndex } from './tmDistinctValuesGridHelper';
+import { needsDisplayValue } from './useTMDistinctValuesMetadataDisplay';
+/** Nel risultato dei valori distinti la prima colonna è il valore, la seconda il numero di documenti che lo contengono */
+const COUNT_COL_INDEX = 1;
+/** Numero massimo di valori distinti richiesti al server: il conteggio dice quanti ne sono arrivati sul totale */
+const MAX_DISTINCT_VALUES = 10000;
+/**
+ * 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 const useTMDistinctValuesSource = ({ tid, mid, display }) => {
+    const { loadDisplayCachesAsync, displayValueColumnProps, getMetadataDisplayValue } = display;
+    const [md, setMd] = useState();
+    const [dataSource, setDataSource] = useState([]);
+    const [counts, setCounts] = useState();
+    // Identifica la richiesta corrente: dopo ogni await le risposte delle richieste obsolete vengono scartate
+    const requestIdRef = useRef(0);
+    // Cambiando campo i valori distinti vanno ricaricati: sono la sorgente su cui si torna cambiando
+    // modalità e quella da cui viene il metadato del campo
+    useEffect(() => { loadAsync(); }, [tid, mid]);
+    const loadAsync = async () => {
+        if (!tid)
+            return;
+        const requestId = ++requestIdRef.current;
+        const isStale = () => requestId !== requestIdRef.current;
+        // Svuota subito la griglia: evita di mostrare i valori del tid/mid precedente durante il caricamento
+        setDataSource([]);
+        setCounts(undefined);
+        try {
+            TMSpinner.show({ description: 'Caricamento dei valori distinti...' });
+            const dtd = await DcmtTypeListCacheService.GetAsync(tid, true);
+            const currentMd = dtd?.metadata?.find(o => o.id === mid);
+            const result = await SDK_Globals.tmSession?.NewSearchEngine().GetDistinctValuesAsync(tid, mid, MAX_DISTINCT_VALUES);
+            if (isStale())
+                return;
+            // La prima colonna del risultato è quella dei valori distinti
+            await loadDisplayCachesAsync([currentMd], result?.dtdResult?.rows);
+            if (isStale())
+                return;
+            setMd(currentMd);
+            setDataSource(convertDataTableToObject(result?.dtdResult));
+            setCounts({ returned: result?.dcmtsReturned ?? 0, found: result?.dcmtsFound ?? 0 });
+        }
+        catch (e) {
+            if (isStale())
+                return;
+            TMExceptionBoxManager.show({ exception: e });
+        }
+        finally {
+            TMSpinner.hide();
+        }
+    };
+    const columns = useMemo(() => {
+        const isDateColumn = md?.dataType === MetadataDataTypes.DateTime;
+        return ([
+            {
+                dataField: 'value', dataType: isDateColumn ? 'date' : 'string', caption: md?.nameLoc,
+                ...(isDateColumn && { format: getDateDisplayFormat(md?.format?.format, md?.format?.formatCulture) }),
+                ...displayValueColumnProps(md, 'value')
+            },
+            { dataField: 'Count', dataType: 'number', caption: 'N°' }
+        ]);
+    }, [md, displayValueColumnProps]);
+    // La colonna del valore mostra la data formattata o la descrizione: la ricerca va fatta su quel testo
+    const searchTextGetters = useMemo(() => {
+        const getters = new Map();
+        if (md?.dataType === MetadataDataTypes.DateTime) {
+            getters.set('value', (rowData) => getDateDisplayText(rowData?.value, md?.format?.format, md?.format?.formatCulture));
+        }
+        else if (needsDisplayValue(md)) {
+            getters.set('value', (rowData) => String(getMetadataDisplayValue(md, rowData?.value) ?? ''));
+        }
+        return getters;
+    }, [md, getMetadataDisplayValue]);
+    const customizeColumns = useMemo(() => customizeSearchByDisplayText(searchTextGetters), [searchTextGetters]);
+    return { md, dataSource, counts, columns, customizeColumns, loadAsync };
+};
+const convertDataTableToObject = (dtdResult) => {
+    if (!dtdResult?.columns?.length || !dtdResult?.rows?.length)
+        return [];
+    // Descrittori di colonna calcolati una sola volta invece che per ogni riga
+    const columns = [];
+    dtdResult.columns.forEach((col, colIndex) => {
+        if (col?.caption) {
+            columns.push({ index: colIndex, key: colIndex === 0 ? "value" : col.caption, isNumber: col.dataType === DataColumnTypes.Number });
+        }
+    });
+    // I valori più frequenti in testa: il conteggio è nella seconda colonna del risultato
+    const sortedRows = dtdResult.rows.slice().sort((a, b) => (Number(b?.[COUNT_COL_INDEX]) || 0) - (Number(a?.[COUNT_COL_INDEX]) || 0));
+    return withRowIndex(sortedRows.map((row) => {
+        const rowObject = {};
+        columns.forEach((col) => {
+            rowObject[col.key] = col.isNumber ? row?.[col.index]?.replace('.', ',') : row?.[col.index] ?? null;
+        });
+        return rowObject;
+    }));
+};