@topconsultnpm/sdkui-react 6.22.0-dev2.16 → 6.22.0-dev2.18

package/lib/components/viewers/TMTidViewer.js

@@ -259,7 +259,7 @@ export const TMDcmtTypeIcon = ({ dtd }) => {
     return (_jsx(TMDcmtTypeTooltip, { dtd: dtd, children: icon }));
 };
 export const TMDcmtTypeTooltip = ({ dtd, children }) => {
-    return (_jsx("div", { style: { pointerEvents: 'all' }, children: _jsx(TMTooltip, { content: renderDTDTooltipContent(dtd), children: children }) }));
+    return (_jsx("div", { style: { pointerEvents: 'all' }, children: _jsx(TMTooltip, { allowContentInteraction: true, content: renderDTDTooltipContent(dtd), children: children }) }));
 };
 const TMTidViewer = ({ tmSession, tid, did, showIcon = false, color, showId = false, noneSelectionText = `<${SDKUI_Localizator.NoneSelection}>` }) => {
     const [dtd, setDtd] = useState();
@@ -297,29 +297,43 @@ const TMTidViewer = ({ tmSession, tid, did, showIcon = false, color, showId = fa
             textOverflow: 'ellipsis'
         }, children: [showIcon && dtd && _jsx(TMDcmtTypeIcon, { dtd: dtd }), _jsx("p", { title: displayName(), style: {
                     textAlign: 'left',
+                    margin: 0,
                     marginLeft: showIcon ? '5px' : '',
-                    color: color ?? (dtd?.isView ? 'red' : TMColors.primary),
+                    color: dtd?.isView ? 'red' : (color ?? TMColors.primary),
                     whiteSpace: 'nowrap',
                     overflow: 'hidden',
                     textOverflow: 'ellipsis',
                     // paddingRight: '10px'
-                }, children: displayName() }), showId && _jsx("p", { style: { padding: '0px 3px' }, children: `(TID: ${tid})` })] }));
+                }, children: displayName() }), showId && _jsx("p", { style: { padding: '0px 3px', margin: 0 }, children: `(TID: ${tid})` })] }));
 };
 export default TMTidViewer;
 export const cellRenderTID = (data, noneSelectionText) => {
     return (_jsx(TMTidViewer, { tid: data.value, noneSelectionText: noneSelectionText }));
 };
-/** Componente per mostrare il metodo di visualizzazione del nome documento (carica i metadati dalla cache se necessario) */
+/** Metodi di visualizzazione già richiesti, per non ricaricare i metadati ad ogni riapertura del tooltip */
+const displayNameMethodCache = new Map();
 const TMDisplayNameMethodItem = ({ dtd }) => {
-    const [displayNameMethod, setDisplayNameMethod] = useState('...');
-    useEffect(() => {
-        const fetchDisplayNameMethod = async () => {
+    const [displayNameMethod, setDisplayNameMethod] = useState(() => dtd.id ? displayNameMethodCache.get(dtd.id) : undefined);
+    const [isLoading, setIsLoading] = useState(false);
+    const onShowClick = async (e) => {
+        /* Un click qualsiasi chiude il tooltip: senza questo il risultato non sarebbe mai visibile */
+        e.stopPropagation();
+        if (isLoading || displayNameMethod)
+            return;
+        setIsLoading(true);
+        try {
             const method = await getDTDDisplayNameInfo(dtd);
+            if (dtd.id)
+                displayNameMethodCache.set(dtd.id, method);
             setDisplayNameMethod(method);
-        };
-        fetchDisplayNameMethod();
-    }, [dtd]);
-    return _jsx(StyledTooltipItem, { children: `${SDKUI_Localizator.DisplayNameMethod}: ${displayNameMethod}` });
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    return (_jsxs(StyledTooltipItem, { children: [`${SDKUI_Localizator.DisplayNameMethod}: `, displayNameMethod ?? (isLoading
+                ? `${SDKUI_Localizator.Loading} ...`
+                : _jsx("span", { style: { color: TMColors.primary, cursor: 'pointer', textDecoration: 'underline' }, onClick: onShowClick, children: SDKUI_Localizator.Details }))] }));
 };
 export const renderDTDTooltipContent = (dtd) => {
     const mapAccessLevelToLocalizedString = (level) => {

package/lib/helper/SDKUI_Globals.d.ts

@@ -67,6 +67,18 @@ export declare class ThemeSettings {
 export declare const DEFAULT_PREVIEW_THRESHOLD = 500;
 export declare const DEFAULT_PAGE_SIZE = 100;
 export declare const DEFAULT_MAX_DCMTS_TO_BE_RETURNED = 200;
+export declare const DEFAULT_QUICK_SEARCH_MAX_DCMTS = 1000;
+/** Ricerca rapida configurata come sorgente alternativa dei valori distinti di un campo */
+export declare class DistinctValuesQuickSearchSettings {
+    /** Tipo documento su cui viene eseguita la ricerca rapida */
+    tid: number | undefined;
+    /** ID della ricerca salvata (SavedQueryDescriptor) da eseguire; SYS_ALL_DCMTS_SQD_ID per la ricerca di sistema con tutti i documenti del tipo documento */
+    sqdId: number | undefined;
+    /** Metadato del risultato da cui viene prelevato il valore */
+    mid: number | undefined;
+    /** Numero massimo di documenti restituiti dalla ricerca rapida */
+    maxDcmtsToBeReturned: number;
+}
 export declare class SearchSettings {
     autoFindReferences: ObjectClasses[];
     invoiceRetrieveFormat: InvoiceRetrieveFormats;
@@ -86,7 +98,15 @@ export declare class SearchSettings {
     };
     relationExpandLevel: number;
     relationShowZeroDcmts: boolean;
+    /** Ricerche rapide configurate per i valori distinti: una per ogni campo, con chiave "tid_mid" */
+    distinctValuesQuickSearches: {
+        [fieldKey: string]: DistinctValuesQuickSearchSettings;
+    };
 }
+/** Ricerca rapida configurata per il campo, se presente */
+export declare const getDistinctValuesQuickSearch: (tid: number | undefined, mid: number | undefined) => DistinctValuesQuickSearchSettings | undefined;
+export declare const saveDistinctValuesQuickSearch: (tid: number | undefined, mid: number | undefined, settings: DistinctValuesQuickSearchSettings) => void;
+export declare const removeDistinctValuesQuickSearch: (tid: number | undefined, mid: number | undefined) => void;
 export declare class FloatingMenuBarSettings {
     orientation?: 'horizontal' | 'vertical';
     itemIds?: string[];

package/lib/helper/SDKUI_Globals.js

@@ -130,6 +130,20 @@ export class ThemeSettings {
 export const DEFAULT_PREVIEW_THRESHOLD = 500; // KB
 export const DEFAULT_PAGE_SIZE = 100;
 export const DEFAULT_MAX_DCMTS_TO_BE_RETURNED = 200;
+export const DEFAULT_QUICK_SEARCH_MAX_DCMTS = 1000;
+/** Ricerca rapida configurata come sorgente alternativa dei valori distinti di un campo */
+export class DistinctValuesQuickSearchSettings {
+    constructor() {
+        /** Tipo documento su cui viene eseguita la ricerca rapida */
+        this.tid = undefined;
+        /** ID della ricerca salvata (SavedQueryDescriptor) da eseguire; SYS_ALL_DCMTS_SQD_ID per la ricerca di sistema con tutti i documenti del tipo documento */
+        this.sqdId = undefined;
+        /** Metadato del risultato da cui viene prelevato il valore */
+        this.mid = undefined;
+        /** Numero massimo di documenti restituiti dalla ricerca rapida */
+        this.maxDcmtsToBeReturned = DEFAULT_QUICK_SEARCH_MAX_DCMTS;
+    }
+}
 export class SearchSettings {
     constructor() {
         this.autoFindReferences = [];
@@ -144,8 +158,38 @@ export class SearchSettings {
         this.panelLayout = {};
         this.relationExpandLevel = 4; // Livello di espansione predefinito per le correlazioni
         this.relationShowZeroDcmts = false;
+        /** Ricerche rapide configurate per i valori distinti: una per ogni campo, con chiave "tid_mid" */
+        this.distinctValuesQuickSearches = {};
     }
 }
+/** Il campo da cui viene aperto il pannello dei valori distinti è identificato dalla coppia (tid, mid) */
+const distinctValuesFieldKey = (tid, mid) => `${tid}_${mid}`;
+/** Ricerca rapida configurata per il campo, se presente */
+export const getDistinctValuesQuickSearch = (tid, mid) => {
+    if (!tid || !mid)
+        return undefined;
+    // Le impostazioni salvate da versioni precedenti non hanno la mappa: va gestita l'assenza
+    return SDKUI_Globals.userSettings.searchSettings.distinctValuesQuickSearches?.[distinctValuesFieldKey(tid, mid)];
+};
+export const saveDistinctValuesQuickSearch = (tid, mid, settings) => {
+    if (!tid || !mid)
+        return;
+    // Il proxy delle impostazioni persiste solo intercettando l'assegnazione di una proprietà: la mappa va riassegnata per intero
+    SDKUI_Globals.userSettings.searchSettings.distinctValuesQuickSearches = {
+        ...SDKUI_Globals.userSettings.searchSettings.distinctValuesQuickSearches,
+        [distinctValuesFieldKey(tid, mid)]: settings,
+    };
+};
+export const removeDistinctValuesQuickSearch = (tid, mid) => {
+    if (!tid || !mid)
+        return;
+    const fieldKey = distinctValuesFieldKey(tid, mid);
+    const quickSearches = SDKUI_Globals.userSettings.searchSettings.distinctValuesQuickSearches;
+    if (!quickSearches?.[fieldKey])
+        return;
+    const { [fieldKey]: removedSettings, ...remainingQuickSearches } = quickSearches;
+    SDKUI_Globals.userSettings.searchSettings.distinctValuesQuickSearches = remainingQuickSearches;
+};
 export class FloatingMenuBarSettings {
 }
 export class ArchivingSettings {

package/lib/helper/SDKUI_Localizator.d.ts

@@ -657,6 +657,7 @@ export declare class SDKUI_Localizator {
     static get QueryDefine(): "Abfrage definieren" | "Query define" | "Definir consulta" | "Défine query" | "Definir query" | "Definisci query";
     static get Query_EnterAlias(): "Geben Sie einen Alias ​​ein" | "Enter an alias" | "Introducir un alias" | "Entrez un alias" | "Digite um nome de alias" | "Inserire un alias";
     static get QueryParamBind(): "Query-Parameter erweitern" | "Fill query parameters" | "Valorizar parámetros consulta" | "Ajoute la valeur à les paramètres de la query" | "Melhora parâmetros de query" | "Valorizza parametri query";
+    static get QuickSearchSettings_DeleteConfirmFor1(): "Schnellsuche-Konfiguration für '{{0}}' löschen?" | "Delete the quick search setup for '{{0}}'?" | "¿Eliminar la configuración de la búsqueda rápida de '{{0}}'?" | "Supprimer la configuration de la recherche rapide de '{{0}}' ?" | "Eliminar a configuração da pesquisa rápida de '{{0}}'?" | "Eliminare la configurazione della ricerca rapida di '{{0}}'?";
     static get ReadOnly(): "Nur Lesen" | "Read only" | "Solo lectura" | "En lecture seule" | "Somente leitura" | "Solo lettura";
     static get Reassign(): "Neu zuweisen" | "Reassign" | "Reasignar" | "Réaffecter" | "Reatribuir" | "Riassegna";
     static get RefersTo(): string;

package/lib/helper/SDKUI_Localizator.js

@@ -6542,6 +6542,16 @@ export class SDKUI_Localizator {
             default: return "Valorizza parametri query";
         }
     }
+    static get QuickSearchSettings_DeleteConfirmFor1() {
+        switch (this._cultureID) {
+            case CultureIDs.De_DE: return "Schnellsuche-Konfiguration für '{{0}}' löschen?";
+            case CultureIDs.En_US: return "Delete the quick search setup for '{{0}}'?";
+            case CultureIDs.Es_ES: return "¿Eliminar la configuración de la búsqueda rápida de '{{0}}'?";
+            case CultureIDs.Fr_FR: return "Supprimer la configuration de la recherche rapide de '{{0}}' ?";
+            case CultureIDs.Pt_PT: return "Eliminar a configuração da pesquisa rápida de '{{0}}'?";
+            default: return "Eliminare la configurazione della ricerca rapida di '{{0}}'?";
+        }
+    }
     static get ReadOnly() {
         switch (this._cultureID) {
             case CultureIDs.De_DE: return "Nur Lesen";

package/lib/helper/dataGridSearchHelper.d.ts

@@ -0,0 +1,28 @@
+import { MetadataFormats } from '@topconsultnpm/sdk-ts';
+/** Testo mostrato in una colonna per una riga: è quello su cui va cercato ciò che l'utente digita */
+export type SearchTextGetter = (rowData: any) => string;
+/** Testo con cui una data viene mostrata nella griglia: è quello che l'utente vede e quindi quello che cerca */
+export declare const getDateDisplayText: (value: any, format: MetadataFormats | undefined, formatCulture: string | undefined | null) => string;
+/** Testo con cui un numero viene mostrato nella griglia (separatore delle migliaia, valuta, decimali) */
+export declare const getNumberDisplayText: (value: any, format: MetadataFormats | undefined, formatCulture: string) => string;
+/**
+ * Dirotta la ricerca della griglia sul testo mostrato, per le colonne indicate (chiave: il `dataField`).
+ *
+ * La ricerca di DevExtreme lavora sul valore archiviato, quindi non trova nulla dove il testo mostrato è
+ * diverso:
+ * - **date**, che nei dati sono stringhe ISO: DevExtreme prova a interpretare il testo digitato con il
+ *   formato della colonna, non riesce (il formato è un formatter personalizzato, non un pattern) e scarta
+ *   la colonna dalla ricerca — cercando `29/01/2023` non trova nulla;
+ * - **numeri formattati**, per lo stesso motivo (separatore delle migliaia, simbolo di valuta);
+ * - **liste dati e utenti**, dove viene confrontata la chiave archiviata invece della descrizione
+ *   visualizzata — cercando `FATTURA` non trova nulla, cercando `TD01` sì.
+ *
+ * Da passare a `customizeColumns` della griglia. Va fatto lì perché solo lì è disponibile la
+ * `calculateFilterExpression` predefinita di DevExtreme, che resta in uso per il filtro di intestazione e
+ * per il generatore di filtri: quelli funzionano già correttamente e vanno lasciati intatti.
+ *
+ * @example
+ * const searchTextGetters = useMemo(() => new Map([['TM_1_2', (row) => getDateDisplayText(row?.TM_1_2, format, culture)]]), [...]);
+ * const customizeColumns = useMemo(() => customizeSearchByDisplayText(searchTextGetters), [searchTextGetters]);
+ */
+export declare const customizeSearchByDisplayText: (searchTextGetters: Map<string, SearchTextGetter>) => (columns: Array<any>) => void;

package/lib/helper/dataGridSearchHelper.js

@@ -0,0 +1,51 @@
+import { formatDateTimeByMetadataFormat, formatNumberByMetadataFormat } from './TMUtils';
+/** Testo con cui una data viene mostrata nella griglia: è quello che l'utente vede e quindi quello che cerca */
+export const getDateDisplayText = (value, format, formatCulture) => {
+    if (value === undefined || value === null || value === '')
+        return '';
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? '' : formatDateTimeByMetadataFormat(date, format, formatCulture);
+};
+/** Testo con cui un numero viene mostrato nella griglia (separatore delle migliaia, valuta, decimali) */
+export const getNumberDisplayText = (value, format, formatCulture) => {
+    if (value === undefined || value === null || value === '')
+        return '';
+    return formatNumberByMetadataFormat(value, format, formatCulture);
+};
+/**
+ * Dirotta la ricerca della griglia sul testo mostrato, per le colonne indicate (chiave: il `dataField`).
+ *
+ * La ricerca di DevExtreme lavora sul valore archiviato, quindi non trova nulla dove il testo mostrato è
+ * diverso:
+ * - **date**, che nei dati sono stringhe ISO: DevExtreme prova a interpretare il testo digitato con il
+ *   formato della colonna, non riesce (il formato è un formatter personalizzato, non un pattern) e scarta
+ *   la colonna dalla ricerca — cercando `29/01/2023` non trova nulla;
+ * - **numeri formattati**, per lo stesso motivo (separatore delle migliaia, simbolo di valuta);
+ * - **liste dati e utenti**, dove viene confrontata la chiave archiviata invece della descrizione
+ *   visualizzata — cercando `FATTURA` non trova nulla, cercando `TD01` sì.
+ *
+ * Da passare a `customizeColumns` della griglia. Va fatto lì perché solo lì è disponibile la
+ * `calculateFilterExpression` predefinita di DevExtreme, che resta in uso per il filtro di intestazione e
+ * per il generatore di filtri: quelli funzionano già correttamente e vanno lasciati intatti.
+ *
+ * @example
+ * const searchTextGetters = useMemo(() => new Map([['TM_1_2', (row) => getDateDisplayText(row?.TM_1_2, format, culture)]]), [...]);
+ * const customizeColumns = useMemo(() => customizeSearchByDisplayText(searchTextGetters), [searchTextGetters]);
+ */
+export const customizeSearchByDisplayText = (searchTextGetters) => (columns) => {
+    columns.forEach((column) => {
+        const getSearchText = column?.dataField ? searchTextGetters.get(column.dataField) : undefined;
+        // customizeColumns viene richiamata a ogni aggiornamento delle colonne: senza il marcatore i wrapper si anniderebbero
+        if (!getSearchText || column.tmSearchByDisplayText)
+            return;
+        const defaultCalculateFilterExpression = column.calculateFilterExpression;
+        // Senza questo DevExtreme prova a convertire il testo digitato nel tipo della colonna e, non riuscendo, la scarta
+        column.parseValue = (text) => text;
+        column.calculateFilterExpression = function (filterValue, selectedFilterOperation, target) {
+            if (target === 'search')
+                return [getSearchText, 'contains', filterValue];
+            return defaultCalculateFilterExpression?.apply(this, arguments);
+        };
+        column.tmSearchByDisplayText = true;
+    });
+};

package/lib/helper/index.d.ts

@@ -5,6 +5,7 @@ export * from './Globalization';
 export * from './TMIcons';
 export * from './TMImageLibrary';
 export * from './helpers';
+export * from './dataGridSearchHelper';
 export * from './queryHelper';
 export * from './TMUtils';
 export * from './TMCommandsContextMenu';

package/lib/helper/index.js

@@ -5,6 +5,7 @@ export * from './Globalization';
 export * from './TMIcons';
 export * from './TMImageLibrary';
 export * from './helpers';
+export * from './dataGridSearchHelper';
 export * from './queryHelper';
 export * from './TMUtils';
 export * from './TMCommandsContextMenu';

package/lib/helper/queryHelper.d.ts

@@ -14,6 +14,8 @@ export declare function addWhereClausesForConnect(qd: QueryDescriptor): void;
 export declare function getDefaultOperator(dataDomain: MetadataDataDomains | undefined, dataType: MetadataDataTypes | undefined): QueryOperators.Equal | QueryOperators.Contain | QueryOperators.In;
 export declare const getQD: (tid: number | undefined, easyOr: boolean, newMaxDcmtsToBeReturned: number) => Promise<QueryDescriptor | undefined>;
 export declare const getWorkItemSetIDAsync: (vid: number, did: number) => Promise<string | undefined>;
+/** Id assegnato alla ricerca di sistema con tutti i documenti: non è in cache, va ricostruita a runtime con getSysAllDcmtsSQD */
+export declare const SYS_ALL_DCMTS_SQD_ID = 1;
 export declare const getSysAllDcmtsSQD: (tid: number | undefined, easyOr: boolean) => Promise<SavedQueryDescriptor>;
 export declare const searchResultToMetadataValues: (tid: number | undefined, dtd: DataTableDescriptor | undefined, rows: string[], mids: number[], metadata: MetadataDescriptor[], layoutMode: LayoutModes, isReadOnlyOrigin?: boolean) => MetadataValueDescriptorEx[];
 export declare const handleArchiveVisibility: (md: MetadataDescriptor) => boolean;

package/lib/helper/queryHelper.js

@@ -251,9 +251,11 @@ export const getWorkItemSetIDAsync = async (vid, did) => {
     let result = await SDK_Globals.tmSession?.NewSearchEngine().SearchByIDAsync(qd);
     return result?.dtdResult?.rows?.[0]?.[0];
 };
+/** Id assegnato alla ricerca di sistema con tutti i documenti: non è in cache, va ricostruita a runtime con getSysAllDcmtsSQD */
+export const SYS_ALL_DCMTS_SQD_ID = 1;
 export const getSysAllDcmtsSQD = async (tid, easyOr) => {
     let sqd = new SavedQueryDescriptor();
-    sqd.id = 1;
+    sqd.id = SYS_ALL_DCMTS_SQD_ID;
     sqd.masterTID = tid;
     sqd.isEasyWhere = 1;
     sqd.name = SDKUI_Localizator.AllDcmts;

package/lib/hooks/tmDistinctValuesGridHelper.d.ts

@@ -0,0 +1,16 @@
+import { DataColumnDescriptor, DataColumnTypes, MetadataDescriptor, MetadataFormats } from '@topconsultnpm/sdk-ts';
+/**
+ * Funzioni condivise dalle due sorgenti di TMDistinctValues (valori distinti e ricerca rapida):
+ * stanno fuori dagli hook perché non dipendono da alcuno stato.
+ */
+export declare const withRowIndex: <T>(rows: Array<T>) => T[];
+export declare const toGridDataType: (dataType: DataColumnTypes | undefined) => "string" | "number" | "datetime" | "boolean";
+export declare const getMetadataName: (columnMd: MetadataDescriptor | undefined) => string | undefined;
+export declare const getDateDisplayFormat: (format: MetadataFormats | undefined, formatCulture: string | undefined | null) => {
+    formatter: (value: string | number | Date) => string;
+};
+/**
+ * Risolve il MID della colonna di un risultato di ricerca: la proprietà estesa è la fonte principale,
+ * in mancanza resta l'allineamento posizionale tra selectMIDs e colonne del risultato.
+ */
+export declare const getColumnMid: (column: DataColumnDescriptor | undefined, selectMIDs: number[] | undefined, columnIndex: number) => number;

package/lib/hooks/tmDistinctValuesGridHelper.js

@@ -0,0 +1,31 @@
+import { DataColumnTypes, SDK_Globals } from '@topconsultnpm/sdk-ts';
+import { formatDateTimeByMetadataFormat } from '../helper';
+/**
+ * Funzioni condivise dalle due sorgenti di TMDistinctValues (valori distinti e ricerca rapida):
+ * stanno fuori dagli hook perché non dipendono da alcuno stato.
+ */
+// rowIndex è la chiave delle griglie di TMDistinctValues: va riallineato all'ordine finale delle righe
+export const withRowIndex = (rows) => {
+    rows.forEach((row, index) => { row.rowIndex = index; });
+    return rows;
+};
+export const toGridDataType = (dataType) => {
+    switch (dataType) {
+        case DataColumnTypes.DateTime: return 'datetime';
+        case DataColumnTypes.Bool: return 'boolean';
+        case DataColumnTypes.Number: return 'number';
+        default: return 'string';
+    }
+};
+// Nome del metadato con cui viene intestata la colonna, nella lingua scelta dall'utente
+export const getMetadataName = (columnMd) => (SDK_Globals.useLocalizedName ? columnMd?.nameLoc : columnMd?.name) ?? columnMd?.name ?? columnMd?.nameLoc ?? undefined;
+// Le date vanno mostrate con il formato definito sul metadato, come nel risultato di ricerca
+export const getDateDisplayFormat = (format, formatCulture) => ({
+    // La griglia passa al formatter un oggetto Date già istanziato, ma il valore può arrivare anche come stringa
+    formatter: (value) => formatDateTimeByMetadataFormat(value instanceof Date ? value : new Date(value), format, formatCulture)
+});
+/**
+ * Risolve il MID della colonna di un risultato di ricerca: la proprietà estesa è la fonte principale,
+ * in mancanza resta l'allineamento posizionale tra selectMIDs e colonne del risultato.
+ */
+export const getColumnMid = (column, selectMIDs, columnIndex) => Number(column?.extendedProperties?.['MID'] ?? 0) || (selectMIDs?.[columnIndex] ?? 0);

package/lib/hooks/useCaseFlowApprove.d.ts

@@ -0,0 +1,56 @@
+import { CaseFlowInstanceDescriptor, CaseFlowWorkItem } from '@topconsultnpm/sdk-ts';
+/**
+ * Attività (workitem) delle PRATICHE assegnate all'utente, con il documento su
+ * cui lavorano già risolto.
+ *
+ * Gemello di `useWorkflowApprove` per il modulo CaseFlow: i dati stanno in una
+ * cache di modulo e le istanze del hook si sincronizzano con un evento, così il
+ * form del documento — da qualunque punto venga aperto — sa che su quel TID/DID
+ * c'è una firma da fare o un'approvazione da dare, senza che il chiamante debba
+ * passargli nulla.
+ */
+/** Workitem di pratica già risolto sul documento cui si riferisce. */
+export interface CaseFlowDcmtWorkItem {
+    caseflow: CaseFlowInstanceDescriptor;
+    workItem: CaseFlowWorkItem;
+    tid: number;
+    did: number;
+}
+/**
+ * Ricarica i workitem di pratica dell'utente. Con `force` ignora la finestra
+ * anti-raffica (da usare dopo un'operazione che li ha modificati).
+ */
+export declare const refreshCaseFlowApproveData: (force?: boolean) => Promise<void>;
+/**
+ * Workitem di pratica pendenti su quel documento (lettura sincrona dalla cache).
+ *
+ * TID/DID vanno NORMALIZZATI: pur essendo tipati `number`, arrivano come stringhe
+ * quando il documento è aperto da una griglia (righe di datagrid) — per lo stesso
+ * motivo il resto della libreria fa `Number(TID)`/`Number(DID)` in ogni confronto.
+ * Senza normalizzazione il confronto stretto falliva, e l'attività risultava
+ * assente aprendo il documento dalla ricerca mentre compariva dal widget "Per te".
+ */
+export declare const getCaseFlowWorkItemsByDcmt: (tid?: number | string, did?: number | string) => CaseFlowDcmtWorkItem[];
+/** Svuota la cache (logout / cambio archivio). */
+export declare const clearCaseFlowApproveData: () => void;
+/** Completa il workitem di pratica e ricarica la cache. */
+export declare const completeCaseFlowWorkItem: (item: CaseFlowDcmtWorkItem, comment?: string) => Promise<void>;
+/** Rifiuta il workitem di pratica (motivo obbligatorio) e ricarica la cache. */
+export declare const rejectCaseFlowWorkItem: (item: CaseFlowDcmtWorkItem, reason: string) => Promise<void>;
+/**
+ * Completa l'attività di FIRMA di una pratica sul documento indicato, se esiste.
+ * La chiama il viewer di firma quando la firma è riuscita: è il gemello di quanto
+ * già avviene per i workitem del workflow legacy.
+ * @returns true se un'attività è stata completata.
+ */
+export declare const completeCaseFlowSignatureForDcmt: (tid: number | string, did: number | string, comment?: string) => Promise<boolean>;
+/**
+ * Attività di pratica sul documento indicato. Senza sessione o senza attività
+ * l'elenco è vuoto e nulla cambia nella UI.
+ */
+export declare const useCaseFlowApprove: (tid?: number | string, did?: number | string) => {
+    caseFlowWorkItems: CaseFlowDcmtWorkItem[];
+    refreshCaseFlowApprove: (force?: boolean) => Promise<void>;
+    completeCaseFlowWorkItem: (item: CaseFlowDcmtWorkItem, comment?: string) => Promise<void>;
+    rejectCaseFlowWorkItem: (item: CaseFlowDcmtWorkItem, reason: string) => Promise<void>;
+};

package/lib/hooks/useCaseFlowApprove.js

@@ -0,0 +1,157 @@
+import { useCallback, useEffect, useState } from 'react';
+import { SDK_Globals } from '@topconsultnpm/sdk-ts';
+import { CaseFlowService } from '../services/caseflow/CaseFlowService';
+import { getWorkItemTargetDoc, isMoreInfoWorkItem, isSignatureWorkItem } from '../services/caseflow/caseFlowWorkItemUtils';
+const CASEFLOW_APPROVE_CHANGED_EVENT = 'onCaseFlowApproveChange';
+let cache = [];
+let inFlight;
+let lastLoadedAt = 0;
+/**
+ * Finestra minima fra due ricariche: il form del documento chiede un refresh a
+ * ogni apertura e la lista è una scansione delle istanze, non una query puntuale.
+ */
+const MIN_RELOAD_INTERVAL_MS = 15000;
+const notifyChanged = () => {
+    if (typeof window === 'undefined')
+        return;
+    window.dispatchEvent(new CustomEvent(CASEFLOW_APPROVE_CHANGED_EVENT));
+};
+/**
+ * Ricarica la cache: i workitem pendenti dell'utente, risolti sul documento su
+ * cui lavorano. Le richieste di informazioni sono escluse (si rispondono nella
+ * pratica, non sul documento) come i workitem senza documento.
+ */
+const reload = async () => {
+    const userId = SDK_Globals.tmSession?.SessionDescr?.userID;
+    if (userId == null) {
+        cache = [];
+        return;
+    }
+    const groups = await CaseFlowService.getMyPendingWorkItems(userId);
+    const resolved = [];
+    for (const { caseflow, workItems } of groups) {
+        // Le richieste di informazioni si rispondono nella pratica, non sul documento.
+        const relevant = workItems.filter(wi => !isMoreInfoWorkItem(wi));
+        if (relevant.length === 0)
+            continue;
+        // Il TID dell'azione è autorato sul TEMPLATE e non materializzato
+        // sull'istanza: senza template risolto il documento non è calcolabile.
+        if (caseflow.cftid != null) {
+            await CaseFlowService.getTemplate(caseflow.cftid);
+        }
+        // I DOCUMENTI AGGANCIATI non arrivano dalla RetrieveAll (che porta solo i
+        // dati delle card): serve la Retrieve completa, altrimenti `dcmts` è vuoto
+        // e nessun workitem risulterebbe associato a un documento.
+        let instance = caseflow;
+        if ((instance.dcmts?.length ?? 0) === 0 && instance.id != null) {
+            instance = (await CaseFlowService.getCaseflow(instance.id, instance.cftid)) ?? instance;
+        }
+        for (const wi of relevant) {
+            const target = getWorkItemTargetDoc(instance, wi);
+            if (!target)
+                continue;
+            resolved.push({ caseflow: instance, workItem: wi, tid: target.tid, did: target.did });
+        }
+    }
+    cache = resolved;
+    lastLoadedAt = Date.now();
+    // Diagnostica del bring-up: se il Toppy non compare, qui si vede a che punto
+    // la catena si interrompe (nessun workitem / nessun documento risolto).
+    // Rimuovibile una volta stabilizzato il flusso.
+    console.debug('[CaseFlow] attività su documenti:', {
+        istanzeConPendenti: groups.length,
+        workItemPendenti: groups.reduce((n, g) => n + g.workItems.length, 0),
+        risolteSuDocumento: resolved.length,
+        documenti: resolved.map(r => `${r.tid}/${r.did}`),
+    });
+};
+/**
+ * Ricarica i workitem di pratica dell'utente. Con `force` ignora la finestra
+ * anti-raffica (da usare dopo un'operazione che li ha modificati).
+ */
+export const refreshCaseFlowApproveData = async (force = false) => {
+    if (inFlight)
+        return inFlight;
+    if (!force && lastLoadedAt > 0 && Date.now() - lastLoadedAt < MIN_RELOAD_INTERVAL_MS)
+        return;
+    inFlight = reload()
+        .catch(error => { console.error('Errore nel caricare le attività di pratica sui documenti', error); })
+        .finally(() => { inFlight = undefined; notifyChanged(); });
+    return inFlight;
+};
+/**
+ * Workitem di pratica pendenti su quel documento (lettura sincrona dalla cache).
+ *
+ * TID/DID vanno NORMALIZZATI: pur essendo tipati `number`, arrivano come stringhe
+ * quando il documento è aperto da una griglia (righe di datagrid) — per lo stesso
+ * motivo il resto della libreria fa `Number(TID)`/`Number(DID)` in ogni confronto.
+ * Senza normalizzazione il confronto stretto falliva, e l'attività risultava
+ * assente aprendo il documento dalla ricerca mentre compariva dal widget "Per te".
+ */
+export const getCaseFlowWorkItemsByDcmt = (tid, did) => {
+    const t = Number(tid);
+    const d = Number(did);
+    if (!Number.isFinite(t) || !Number.isFinite(d))
+        return [];
+    return cache.filter(r => Number(r.tid) === t && Number(r.did) === d);
+};
+/** Svuota la cache (logout / cambio archivio). */
+export const clearCaseFlowApproveData = () => {
+    cache = [];
+    lastLoadedAt = 0;
+    notifyChanged();
+};
+/** Completa il workitem di pratica e ricarica la cache. */
+export const completeCaseFlowWorkItem = async (item, comment) => {
+    if (item.caseflow.id == null || item.workItem.id == null)
+        return;
+    await CaseFlowService.completeWorkItem(item.caseflow.id, item.workItem.id, comment?.trim() || undefined);
+    await refreshCaseFlowApproveData(true);
+};
+/** Rifiuta il workitem di pratica (motivo obbligatorio) e ricarica la cache. */
+export const rejectCaseFlowWorkItem = async (item, reason) => {
+    if (item.caseflow.id == null || item.workItem.id == null)
+        return;
+    await CaseFlowService.rejectWorkItem(item.caseflow.id, item.workItem.id, reason);
+    await refreshCaseFlowApproveData(true);
+};
+/**
+ * Completa l'attività di FIRMA di una pratica sul documento indicato, se esiste.
+ * La chiama il viewer di firma quando la firma è riuscita: è il gemello di quanto
+ * già avviene per i workitem del workflow legacy.
+ * @returns true se un'attività è stata completata.
+ */
+export const completeCaseFlowSignatureForDcmt = async (tid, did, comment) => {
+    const target = getCaseFlowWorkItemsByDcmt(tid, did).find(r => isSignatureWorkItem(r.workItem));
+    if (!target)
+        return false;
+    await completeCaseFlowWorkItem(target, comment);
+    return true;
+};
+/**
+ * Attività di pratica sul documento indicato. Senza sessione o senza attività
+ * l'elenco è vuoto e nulla cambia nella UI.
+ */
+export const useCaseFlowApprove = (tid, did) => {
+    const readItems = useCallback(() => getCaseFlowWorkItemsByDcmt(tid, did), [tid, did]);
+    const [caseFlowWorkItems, setCaseFlowWorkItems] = useState(readItems);
+    useEffect(() => { setCaseFlowWorkItems(readItems()); }, [readItems]);
+    useEffect(() => {
+        const handleChange = () => setCaseFlowWorkItems(readItems());
+        window.addEventListener(CASEFLOW_APPROVE_CHANGED_EVENT, handleChange);
+        return () => window.removeEventListener(CASEFLOW_APPROVE_CHANGED_EVENT, handleChange);
+    }, [readItems]);
+    // All'apertura di un documento la cache può essere vecchia (attività assegnate
+    // dopo l'ultimo caricamento) o non ancora popolata.
+    useEffect(() => {
+        if (tid == null || did == null)
+            return;
+        void refreshCaseFlowApproveData();
+    }, [tid, did]);
+    return {
+        caseFlowWorkItems,
+        refreshCaseFlowApprove: refreshCaseFlowApproveData,
+        completeCaseFlowWorkItem,
+        rejectCaseFlowWorkItem,
+    };
+};

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