@acorex/cdk 20.2.0-next.19 → 20.2.0-next.20

package/common/index.d.ts

@@ -210,6 +210,13 @@ declare class AXItemClickEvent<T = any> extends AXClickEvent {
     name?: string;
     item: T;
 }
+/**
+ *  Fires each time the user select the element.
+ * @category Events
+ */
+declare class AXItemSelectedEvent<T = any> extends AXEvent {
+    item: T;
+}
 /**
  *  Fires each time the component gets focused.
  * @category Events
@@ -646,6 +653,7 @@ declare function convertArrayToDataSource<T = unknown>(items: T[], options?: {
     key: string;
     pageSize: number;
 }): AXDataSource<T>;
+declare function applyDataSourceQuery<T extends Record<string, unknown>>(items: T[], filter: AXDataSourceFilterOption): T[];
 
 interface AXDataListQuery {
     take?: number;
@@ -920,6 +928,10 @@ declare abstract class MXSelectionValueComponent<T = unknown> extends MXValueCom
     /** Template string for formatting item display text */
     get textTemplate(): string;
     set textTemplate(value: string);
+    private _defaultText;
+    /** Text to display when neither textField nor valueField exist on the item */
+    get defaultText(): string;
+    set defaultText(value: string);
     private _disabledField;
     /** Field name used to determine if an item is disabled */
     get disabledField(): string;
@@ -930,6 +942,13 @@ declare abstract class MXSelectionValueComponent<T = unknown> extends MXValueCom
     set multiple(value: boolean);
     /** Gets the currently selected items */
     get selectedItems(): unknown[];
+    onItemSelected: EventEmitter<AXItemSelectedEvent>;
+    /**
+   * Emitted when an item in the list is clicked.
+   *
+   * @event
+   */
+    onItemClick: EventEmitter<AXItemClickEvent>;
     /**
      * Abstract method to retrieve an item by its key
      * @param key The unique identifier of the item
@@ -977,8 +996,8 @@ declare abstract class MXSelectionValueComponent<T = unknown> extends MXValueCom
      */
     private createCacheKey;
     /**
-     * Normalizes currently selected items and updates the data service
-     */
+  * Normalizes currently selected items and updates the data service
+  */
     private _normalizeSelectedItems;
     /**
      * Unselects the specified items from the selection
@@ -1007,6 +1026,12 @@ declare abstract class MXSelectionValueComponent<T = unknown> extends MXValueCom
      * @returns True if the item is disabled
      */
     isItemDisabled(item: T): boolean;
+    /**
+     * Checks if an item is currently loading
+     * @param item Item to check
+     * @returns True if the item is loading
+     */
+    isItemLoading(item: T): boolean;
     /**
      * Gets the display text for an item using template or text field
      * @param item Item to get display text for
@@ -1027,6 +1052,25 @@ declare abstract class MXSelectionValueComponent<T = unknown> extends MXValueCom
      * Clears only the cache while preserving selected items
      */
     protected softClearSelectionCache(): void;
+    /**
+     * Clears the debouncing cache for specific items to ensure fresh data is displayed
+     */
+    protected clearItemDebouncingCache(item: T): void;
+    /**
+     * Forces a refresh of the display when items are loaded asynchronously
+     * This should be called when the data source is updated
+     */
+    protected refreshDisplay(): void;
+    /**
+     * Refreshes the display for all selected items to ensure consistency
+     * This is useful when the data source has been updated
+     */
+    protected refreshSelectedItemsDisplay(): void;
+    /**
+     * Forces a refresh of all selected items by clearing their debouncing cache
+     * This ensures fresh data is displayed when the data source is updated
+     */
+    protected forceRefreshSelectedItems(): void;
     /**
      * Asynchronously loads an item by its key and caches the result
      * @param key Key to load item by
@@ -1110,5 +1154,5 @@ declare class AXHotkeysService {
     static ɵprov: i0.ɵɵInjectableDeclaration<AXHotkeysService>;
 }
 
-export { AXAutoFocusDirective, AXAutocompleteParentComponent, AXButtonClickEvent, AXClearableComponent, AXClickEvent, AXClosableComponent, AXCommonModule, AXComponent, AXComponentCloseEvent, AXComponentClosedPromise, AXComponentClosing, AXComponentResult, AXDataSource, AXDomService, AXEvent, AXFocusEvent, AXFocusableComponent, AXHotkeyDirective, AXHotkeysService, AXHtmlEvent, AXInfiniteScrollerDirective, AXInvertedColorDirective, AXItemClickEvent, AXListDataSource, AXNgModelDelayedValueChangedDirective, AXOptionChangedEvent, AXPagedComponent, AXRangeChangedEvent, AXResponsiveDirective, AXRippleDirective, AXSearchableComponent, AXSelectionValueChangedEvent, AXValuableComponent, AXValueChangedEvent, AX_LOCATIONS, AX_PLACEMENT_BOTTOM, AX_PLACEMENT_BOTTOM_END, AX_PLACEMENT_BOTTOM_START, AX_PLACEMENT_END, AX_PLACEMENT_END_BOTTOM, AX_PLACEMENT_END_TOP, AX_PLACEMENT_MAP, AX_PLACEMENT_START, AX_PLACEMENT_START_BOTTOM, AX_PLACEMENT_START_TOP, AX_PLACEMENT_TOP, AX_PLACEMENT_TOP_END, AX_PLACEMENT_TOP_START, AX_SELECTION_DATA_TOKEN, AX_STYLE_COLOR_TYPES, AX_STYLE_LOOK_TYPES, MXBaseComponent, MXButtonBaseComponent, MXColorComponent, MXColorLookComponent, MXInputBaseValueComponent, MXInteractiveComponent, MXLookComponent, MXLookableComponent, MXSelectionBridgeService, MXSelectionValueComponent, MXValueComponent, NXButtonComponent, NXClickEvent, NXColorComponent, NXComponent, NXEvent, NXInteractiveComponent, NXLookComponent, NXNativeEvent, NXValueComponent, TAB_META_KEY, convertArrayToDataSource, convertToPlacement };
+export { AXAutoFocusDirective, AXAutocompleteParentComponent, AXButtonClickEvent, AXClearableComponent, AXClickEvent, AXClosableComponent, AXCommonModule, AXComponent, AXComponentCloseEvent, AXComponentClosedPromise, AXComponentClosing, AXComponentResult, AXDataSource, AXDomService, AXEvent, AXFocusEvent, AXFocusableComponent, AXHotkeyDirective, AXHotkeysService, AXHtmlEvent, AXInfiniteScrollerDirective, AXInvertedColorDirective, AXItemClickEvent, AXItemSelectedEvent, AXListDataSource, AXNgModelDelayedValueChangedDirective, AXOptionChangedEvent, AXPagedComponent, AXRangeChangedEvent, AXResponsiveDirective, AXRippleDirective, AXSearchableComponent, AXSelectionValueChangedEvent, AXValuableComponent, AXValueChangedEvent, AX_LOCATIONS, AX_PLACEMENT_BOTTOM, AX_PLACEMENT_BOTTOM_END, AX_PLACEMENT_BOTTOM_START, AX_PLACEMENT_END, AX_PLACEMENT_END_BOTTOM, AX_PLACEMENT_END_TOP, AX_PLACEMENT_MAP, AX_PLACEMENT_START, AX_PLACEMENT_START_BOTTOM, AX_PLACEMENT_START_TOP, AX_PLACEMENT_TOP, AX_PLACEMENT_TOP_END, AX_PLACEMENT_TOP_START, AX_SELECTION_DATA_TOKEN, AX_STYLE_COLOR_TYPES, AX_STYLE_LOOK_TYPES, MXBaseComponent, MXButtonBaseComponent, MXColorComponent, MXColorLookComponent, MXInputBaseValueComponent, MXInteractiveComponent, MXLookComponent, MXLookableComponent, MXSelectionBridgeService, MXSelectionValueComponent, MXValueComponent, NXButtonComponent, NXClickEvent, NXColorComponent, NXComponent, NXEvent, NXInteractiveComponent, NXLookComponent, NXNativeEvent, NXValueComponent, TAB_META_KEY, applyDataSourceQuery, convertArrayToDataSource, convertToPlacement };
 export type { AXAnimationEasing, AXComponentState, AXConnectedPosition, AXDataListFetchCallbackResult, AXDataListFetchDataCallback, AXDataListItems, AXDataListQuery, AXDataSourceByKeyCallback, AXDataSourceCallbackResult, AXDataSourceChangedEvent, AXDataSourceConfig, AXDataSourceFilterOption, AXDataSourceItemExpandedEvent, AXDataSourceLoadCallback, AXDataSourceOperator, AXDataSourceQuery, AXDataSourceSortOption, AXDirection, AXExpandToggleIcons, AXFilterLogic, AXFormValidationRule, AXHotKeyAction, AXLocation, AXOrientation, AXPagedComponentInterface, AXPlacement, AXPlacementType, AXRange, AXScrollPosition, AXSelectionMode, AXSizeType, AXSortOrder, AXStyleColorType, AXStyleLookType, AXStyleSizeType, AXSurfaceType, DisabledCallback, MXComponentOptionChanged, MXComponentOptionChanging, MXComponentSetOption, NormalizedItem };

package/fesm2022/acorex-cdk-common.mjs

@@ -1,7 +1,7 @@
 import * as i0 from '@angular/core';
 import { model, output, Component, inject, ElementRef, signal, afterNextRender, Injectable, ChangeDetectorRef, ViewContainerRef, EventEmitter, DOCUMENT, PLATFORM_ID, Renderer2, Input, Directive, NgModule, InjectionToken, Output, input, effect } from '@angular/core';
 import { AXHtmlUtil } from '@acorex/core/utils';
-import { flatten, clone, cloneDeep, isEqual, omit, set } from 'lodash-es';
+import { flatten, clone, cloneDeep, isEqual, omit, set, get } from 'lodash-es';
 import { isBrowser } from '@acorex/core/platform';
 import { AXValidationService } from '@acorex/core/validation';
 import { coerceBooleanProperty, coerceNumberProperty } from '@angular/cdk/coercion';
@@ -871,6 +871,12 @@ class AXButtonClickEvent extends AXClickEvent {
  */
 class AXItemClickEvent extends AXClickEvent {
 }
+/**
+ *  Fires each time the user select the element.
+ * @category Events
+ */
+class AXItemSelectedEvent extends AXEvent {
+}
 /**
  *  Fires each time the component gets focused.
  * @category Events
@@ -1167,34 +1173,50 @@ class AXDataSource {
     }
 }
 function convertArrayToDataSource(items, options = { key: 'id', pageSize: 100 }) {
+    // Normalize primitives to objects so consumers (e.g., select/list) can rely on
+    // value and text fields without triggering extra byKey lookups.
+    const normalizedItems = items.map((candidate) => {
+        const isObjectItem = candidate != null && typeof candidate === 'object';
+        if (isObjectItem) {
+            return candidate;
+        }
+        // For primitive values, create an object with both key and text
+        return { [options.key]: candidate, text: String(candidate ?? '') };
+    });
     const config = {
         key: options.key,
         pageSize: options.pageSize,
         load: async (e) => {
-            const result = e.filter ? handleSearch(items, e.filter) : items;
+            const itemsForFilter = normalizedItems;
+            const resultNormalized = e.filter
+                ? applyDataSourceQuery(itemsForFilter, e.filter)
+                : itemsForFilter;
+            const result = resultNormalized;
             return {
                 items: result.slice(e.skip, e.skip + e.take),
-                total: result.length,
+                total: resultNormalized.length,
             };
         },
-        byKey: (v) => Promise.resolve(items.find((c) => {
-            return c[options.key] == v;
-        })),
-    };
-    const handleSearch = (items, filter) => {
-        if (!filter?.field || filter.value === undefined || filter.value === null) {
-            return items; // No filter applied
-        }
-        return items.filter((item) => {
-            const itemField = item[filter.field];
-            if (typeof itemField === 'string' && typeof filter.value === 'string') {
-                return itemField.toLowerCase().includes(filter.value.toLowerCase());
-            }
-            return false; // Return false if itemField isn't comparable
-        });
+        byKey: async (v) => 
+        // Search in the normalized list (supports primitive and object arrays)
+        normalizedItems.find((record) => {
+            return record[options.key] == v;
+        }),
     };
     return new AXDataSource(config);
 }
+function applyDataSourceQuery(items, filter) {
+    if (!filter?.field || filter.value === undefined || filter.value === null) {
+        return items; // No filter applied
+    }
+    return items.filter((item) => {
+        const itemField = item[filter.field];
+        if (typeof itemField === 'string' && typeof filter.value === 'string') {
+            return itemField.toLowerCase().includes(filter.value.toLowerCase());
+        }
+        return false; // Return false if itemField isn't comparable
+    });
+}
 
 const AX_STYLE_COLOR_TYPES = [
     'primary',
@@ -1722,8 +1744,18 @@ class MXSelectionValueComponent extends MXValueComponent {
         this._valueField = 'id';
         this._textField = 'text';
         this._textTemplate = '';
+        this._defaultText = '-';
         this._disabledField = 'disabled';
         this._multiple = false;
+        // #endregion
+        // #region Events
+        this.onItemSelected = new EventEmitter();
+        /**
+       * Emitted when an item in the list is clicked.
+       *
+       * @event
+       */
+        this.onItemClick = new EventEmitter();
     }
     /** Field name used to extract the unique value from items */
     get valueField() {
@@ -1746,6 +1778,13 @@ class MXSelectionValueComponent extends MXValueComponent {
     set textTemplate(value) {
         this.setOption({ name: 'textTemplate', value });
     }
+    /** Text to display when neither textField nor valueField exist on the item */
+    get defaultText() {
+        return this._defaultText;
+    }
+    set defaultText(value) {
+        this.setOption({ name: 'defaultText', value });
+    }
     /** Field name used to determine if an item is disabled */
     get disabledField() {
         return this._disabledField;
@@ -1783,16 +1822,22 @@ class MXSelectionValueComponent extends MXValueComponent {
         if (value == null || (isArray && value.length === 0)) {
             return this.multiple ? [] : null;
         }
-        // Normalize items and find by key if needed
+        // Check if items already have text properties to avoid unnecessary findByKey calls
         const itemsToNormalize = isArray ? value : [value];
-        const normalizedItems = this.normalizeItemsList(itemsToNormalize, true);
+        const needsFindByKey = itemsToNormalize.some(item => {
+            if (typeof item === 'object' && item !== null) {
+                return get(item, this.textField) == null;
+            }
+            return true; // Primitive values need findByKey
+        });
+        const normalizedItems = this.normalizeItemsList(itemsToNormalize, needsFindByKey);
         if (normalizedItems.length === 0) {
             return this.multiple ? [] : null;
         }
         // Extract values based on selection mode
         return this.multiple
-            ? normalizedItems.map(item => item[this.valueField])
-            : normalizedItems[0]?.[this.valueField] ?? null;
+            ? normalizedItems.map(item => get(item, this.valueField))
+            : get(normalizedItems[0], this.valueField) ?? null;
     }
     /**
      * Override to normalize selected items when value changes
@@ -1825,22 +1870,24 @@ class MXSelectionValueComponent extends MXValueComponent {
     normalizeItem(item, findByKey = false) {
         const isComplexObject = typeof item === 'object' && item !== null;
         const itemRecord = item;
-        const key = isComplexObject ? String(itemRecord[this.valueField]) : String(item);
+        const valueKey = isComplexObject ? get(itemRecord, this.valueField) : item;
+        const key = valueKey != null ? String(valueKey) : String(item);
         const cacheKey = this.createCacheKey(key);
         // Return cached item if available and has text
         const cachedItem = this.dataService.cacheList[cacheKey];
-        if (cachedItem && cachedItem[this.textField]) {
+        if (cachedItem && get(cachedItem, this.textField) != null) {
             return cachedItem;
         }
-        const hasTextProperty = !isComplexObject || itemRecord[this.textField] != null;
+        const hasTextProperty = !isComplexObject || get(itemRecord, this.textField) != null;
         const normalizedObj = {};
-        if (isComplexObject && hasTextProperty) {
-            // Item already has all required properties
-            Object.assign(normalizedObj, item);
+        // If findByKey is true, we need to resolve the item to get its text
+        // This is needed for string values like 'ir', 'us' that don't have text
+        if (findByKey) {
+            this.handleItemNormalization(normalizedObj, item, key, true, cacheKey);
         }
         else {
-            // Need to find or create item properties
-            this.handleItemNormalization(normalizedObj, item, key, findByKey, cacheKey);
+            // Item already has all required properties, just copy them
+            Object.assign(normalizedObj, item);
         }
         this.dataService.cacheList[cacheKey] = normalizedObj;
         return normalizedObj;
@@ -1867,7 +1914,7 @@ class MXSelectionValueComponent extends MXValueComponent {
         // Set loading state
         obj[this.valueField] = key;
         obj['isLoading'] = true;
-        obj[this.textField] = 'Loading';
+        obj[this.textField] = 'Loading...';
         promise
             .then(result => {
             if (typeof result === 'object' && result) {
@@ -1877,11 +1924,23 @@ class MXSelectionValueComponent extends MXValueComponent {
                 obj[this.valueField] = result || key;
                 obj[this.textField] = result;
             }
+        })
+            .catch(error => {
+            console.warn('Failed to load item by key:', key, error);
+            // On error, keep the original value but mark as failed
+            obj[this.textField] = this.defaultText;
         })
             .finally(() => {
             delete obj['isLoading'];
+            delete obj['_displayTextLoading'];
+            delete obj['_loadingTriggered'];
             this.dataService.cacheList[cacheKey] = obj;
-            this.cdr.markForCheck();
+            // Use setTimeout to defer change detection and prevent immediate re-rendering
+            setTimeout(() => {
+                if (this.cdr) {
+                    this.cdr.markForCheck();
+                }
+            }, 0);
         });
     }
     /**
@@ -1891,12 +1950,16 @@ class MXSelectionValueComponent extends MXValueComponent {
         const isSourceObject = typeof sourceItem === 'object' && sourceItem !== null;
         const sourceRecord = sourceItem;
         if (isComplexSource && isSourceObject) {
-            obj[this.valueField] = sourceRecord[this.valueField];
-            obj[this.textField] = sourceRecord[this.textField];
+            const valueFromSource = get(sourceRecord, this.valueField);
+            const textFromSource = get(sourceRecord, this.textField);
+            obj[this.valueField] = (valueFromSource ?? textFromSource);
+            obj[this.textField] = (textFromSource ?? valueFromSource ?? this.defaultText);
         }
         else {
-            obj[this.valueField] = isSourceObject ? sourceRecord[this.valueField] : sourceItem;
-            obj[this.textField] = isSourceObject ? sourceRecord[this.textField] : sourceItem;
+            const valueFromSource = isSourceObject ? get(sourceRecord, this.valueField) : sourceItem;
+            const textFromSource = isSourceObject ? get(sourceRecord, this.textField) : sourceItem;
+            obj[this.valueField] = (valueFromSource ?? textFromSource);
+            obj[this.textField] = (textFromSource ?? valueFromSource ?? this.defaultText);
         }
     }
     /**
@@ -1906,13 +1969,19 @@ class MXSelectionValueComponent extends MXValueComponent {
         return `k-${key}`;
     }
     /**
-     * Normalizes currently selected items and updates the data service
-     */
+  * Normalizes currently selected items and updates the data service
+  */
     _normalizeSelectedItems() {
         const values = Array.isArray(this.value)
             ? this.value
             : this.value != null ? [this.value] : [];
-        this.dataService.selectedItems = values.map(value => this.normalizeItem(value));
+        // Only call normalizeItem with findByKey=true if the item doesn't have text
+        // This prevents unnecessary API calls for items that already have text
+        this.dataService.selectedItems = values.map(value => {
+            const hasText = typeof value === 'object' && value !== null &&
+                get(value, this.textField) != null;
+            return this.normalizeItem(value, !hasText);
+        });
     }
     // #endregion
     // #region Public Selection Methods
@@ -1926,7 +1995,7 @@ class MXSelectionValueComponent extends MXValueComponent {
             return;
         }
         const normalizedItems = this.normalizeItemsList(items);
-        const newSelectedItems = this.selectedItems.filter(selectedItem => !normalizedItems.some(normalizedItem => normalizedItem[this.valueField] === selectedItem[this.valueField]));
+        const newSelectedItems = this.selectedItems.filter(selectedItem => !normalizedItems.some(normalizedItem => get(normalizedItem, this.valueField) === get(selectedItem, this.valueField)));
         this.commitValue(newSelectedItems, true);
     }
     /**
@@ -1934,13 +2003,20 @@ class MXSelectionValueComponent extends MXValueComponent {
      * @param items Items to select
      */
     selectItems(...items) {
-        if (!items?.length)
+        if (!items?.length) {
             return;
+        }
         const currentValue = Array.isArray(this.value) ? this.value : [this.value];
         const normalizedItems = this.normalizeItemsList(items);
         const newSelectedItems = this.multiple
             ? [...currentValue, ...normalizedItems]
             : normalizedItems;
+        this.onItemSelected.emit({
+            component: this,
+            isUserInteraction: true,
+            item: newSelectedItems[0],
+            htmlElement: this.getHostElement()
+        });
         this.commitValue(newSelectedItems, true);
     }
     /**
@@ -1968,7 +2044,8 @@ class MXSelectionValueComponent extends MXValueComponent {
      */
     isItemSelected(item) {
         const normalizedItem = this.normalizeItem(item);
-        return this.selectedItems.some(selectedItem => selectedItem[this.valueField] === normalizedItem[this.valueField]);
+        const normalizedValue = get(normalizedItem, this.valueField);
+        return this.selectedItems.some(selectedItem => get(selectedItem, this.valueField) === normalizedValue);
     }
     /**
      * Checks if an item is disabled
@@ -1978,9 +2055,18 @@ class MXSelectionValueComponent extends MXValueComponent {
     isItemDisabled(item) {
         const itemRecord = item;
         return (this.disabled ||
-            coerceBooleanProperty(itemRecord[this.disabledField]) === true ||
+            coerceBooleanProperty(get(itemRecord, this.disabledField)) === true ||
             (this.disabledCallback?.({ item, index: -1 }) ?? false));
     }
+    /**
+     * Checks if an item is currently loading
+     * @param item Item to check
+     * @returns True if the item is loading
+     */
+    isItemLoading(item) {
+        const normalizedItem = this.normalizeItem(item);
+        return normalizedItem['isLoading'] === true;
+    }
     // #endregion
     // #region Protected Utility Methods
     /**
@@ -1989,22 +2075,108 @@ class MXSelectionValueComponent extends MXValueComponent {
      * @returns Formatted display text
      */
     getDisplayText(item) {
-        const normalizedItem = this.normalizeItem(item);
+        // Prevent recursive calls that could cause infinite loops
+        if (item && typeof item === 'object' && item['_displayTextLoading']) {
+            return 'Loading...';
+        }
+        // Add timestamp-based debouncing to prevent excessive calls for ALL item types
+        const now = Date.now();
+        const itemKey = typeof item === 'string' ? item : get(item, this.valueField);
+        const cacheKey = this.createCacheKey(String(itemKey));
+        // Check if we have a recent result in the cache to prevent duplicate processing
+        const cachedResult = this.dataService.cacheList[cacheKey];
+        if (cachedResult && cachedResult['_lastDisplayTextCall']) {
+            const timeSinceLastCall = now - cachedResult['_lastDisplayTextCall'];
+            if (timeSinceLastCall < 50) { // 50ms debounce
+                return cachedResult['_lastDisplayTextResult'] || String(itemKey || '');
+            }
+        }
+        // For string values, we need to normalize with findByKey=true to trigger async loading
+        const isStringValue = typeof item === 'string';
+        const normalizedItem = this.normalizeItem(item, isStringValue);
+        // Check if this item is already in the cache with proper text
+        const itemValue = get(normalizedItem, this.valueField);
+        if (itemValue != null && itemValue !== '') {
+            const cacheKey = this.createCacheKey(String(itemValue));
+            const cachedItem = this.dataService.cacheList[cacheKey];
+            if (cachedItem && get(cachedItem, this.textField) != null) {
+                // Use cached text if available
+                const cachedText = get(cachedItem, this.textField);
+                if (cachedText && cachedText !== 'Loading...') {
+                    const result = String(cachedText);
+                    // Cache the timestamp and result for debouncing in the cache (works for all item types)
+                    if (cachedItem) {
+                        cachedItem['_lastDisplayTextCall'] = now;
+                        cachedItem['_lastDisplayTextResult'] = result;
+                    }
+                    return result;
+                }
+            }
+        }
         // Try template formatting first
         if (this.textTemplate) {
             const formattedTemplate = this.formatService.format(this.textTemplate, 'string', normalizedItem);
             if (formattedTemplate !== this.textTemplate) {
-                return formattedTemplate;
+                const result = formattedTemplate;
+                // Cache the timestamp and result for debouncing in the cache
+                if (normalizedItem) {
+                    normalizedItem['_lastDisplayTextCall'] = now;
+                    normalizedItem['_lastDisplayTextResult'] = result;
+                }
+                return result;
             }
         }
         // Use text field or fallback to value field
-        if (normalizedItem[this.textField]) {
-            return String(normalizedItem[this.textField]);
+        const textValue = get(normalizedItem, this.textField);
+        if (textValue != null && textValue !== '') {
+            const result = String(textValue);
+            // Cache the timestamp and result for debouncing in the cache
+            if (normalizedItem) {
+                normalizedItem['_lastDisplayTextCall'] = now;
+                normalizedItem['_lastDisplayTextResult'] = result;
+            }
+            return result;
+        }
+        // If text is missing and item is loading, show loading state
+        if (normalizedItem['isLoading']) {
+            const result = 'Loading...';
+            // Cache the timestamp and result for debouncing in the cache
+            if (normalizedItem) {
+                normalizedItem['_lastDisplayTextCall'] = now;
+                normalizedItem['_lastDisplayTextResult'] = result;
+            }
+            return result;
         }
         // Attempt to load item by key if text is missing
-        const value = normalizedItem[this.valueField];
-        this.loadAndCacheItemByKey(value);
-        return String(value);
+        const value = get(normalizedItem, this.valueField);
+        if (value == null || value === '') {
+            const result = this.defaultText;
+            // Cache the timestamp and result for debouncing in the cache
+            if (normalizedItem) {
+                normalizedItem['_lastDisplayTextCall'] = now;
+                normalizedItem['_lastDisplayTextResult'] = result;
+            }
+            return result;
+        }
+        // If we have a value but no text, trigger async loading only once
+        // Use a flag to prevent multiple calls
+        if (!normalizedItem['_loadingTriggered'] && !normalizedItem[this.textField]) {
+            normalizedItem['_loadingTriggered'] = true;
+            normalizedItem['_displayTextLoading'] = true;
+            // Use setTimeout to defer the async loading and prevent immediate change detection
+            setTimeout(() => {
+                this.loadAndCacheItemByKey(value);
+            }, 0);
+        }
+        // Return the value itself as a fallback
+        // This will be updated once the async loading completes
+        const result = String(value);
+        // Cache the timestamp and result for debouncing in the cache
+        if (normalizedItem) {
+            normalizedItem['_lastDisplayTextCall'] = now;
+            normalizedItem['_lastDisplayTextResult'] = result;
+        }
+        return result;
     }
     /**
      * Gets the value of an item
@@ -2013,7 +2185,7 @@ class MXSelectionValueComponent extends MXValueComponent {
      */
     getValue(item) {
         const normalizedItem = this.normalizeItem(item);
-        return normalizedItem[this.valueField];
+        return get(normalizedItem, this.valueField);
     }
     /**
      * Clears the selection cache and selected items
@@ -2030,6 +2202,52 @@ class MXSelectionValueComponent extends MXValueComponent {
         this.dataService.cacheList = {};
         this.cdr.markForCheck();
     }
+    /**
+     * Clears the debouncing cache for specific items to ensure fresh data is displayed
+     */
+    clearItemDebouncingCache(item) {
+        // Get the cache key for this item
+        const itemKey = typeof item === 'string' ? item : get(item, this.valueField);
+        if (itemKey != null) {
+            const cacheKey = this.createCacheKey(String(itemKey));
+            const cachedItem = this.dataService.cacheList[cacheKey];
+            if (cachedItem) {
+                delete cachedItem['_lastDisplayTextCall'];
+                delete cachedItem['_lastDisplayTextResult'];
+                delete cachedItem['_displayTextLoading'];
+                delete cachedItem['_loadingTriggered'];
+            }
+        }
+    }
+    /**
+     * Forces a refresh of the display when items are loaded asynchronously
+     * This should be called when the data source is updated
+     */
+    refreshDisplay() {
+        this.cdr.markForCheck();
+    }
+    /**
+     * Refreshes the display for all selected items to ensure consistency
+     * This is useful when the data source has been updated
+     */
+    refreshSelectedItemsDisplay() {
+        // Force a refresh of the display without re-normalizing to avoid infinite loops
+        if (this.selectedItems.length > 0) {
+            this.cdr.markForCheck();
+        }
+    }
+    /**
+     * Forces a refresh of all selected items by clearing their debouncing cache
+     * This ensures fresh data is displayed when the data source is updated
+     */
+    forceRefreshSelectedItems() {
+        if (this.selectedItems.length > 0) {
+            this.selectedItems.forEach(item => {
+                this.clearItemDebouncingCache(item);
+            });
+            this.cdr.markForCheck();
+        }
+    }
     // #endregion
     // #region Private Helper Methods
     /**
@@ -2042,12 +2260,29 @@ class MXSelectionValueComponent extends MXValueComponent {
             if (item) {
                 const normalizedItem = this.normalizeItem(item);
                 const cacheKey = this.createCacheKey(String(normalizedItem[this.valueField]));
+                // Update the cache with the loaded item
                 this.dataService.cacheList[cacheKey] = normalizedItem;
-                this.cdr.markForCheck();
+                // Clear loading flags
+                if (this.dataService.cacheList[cacheKey]) {
+                    delete this.dataService.cacheList[cacheKey]['_displayTextLoading'];
+                    delete this.dataService.cacheList[cacheKey]['_loadingTriggered'];
+                }
+                // Use setTimeout to defer change detection and prevent immediate re-rendering
+                setTimeout(() => {
+                    if (this.cdr) {
+                        this.cdr.markForCheck();
+                    }
+                }, 0);
             }
         }
         catch (error) {
             console.warn('Failed to load item by key:', key, error);
+            // Clear loading flags on error too
+            const cacheKey = this.createCacheKey(String(key));
+            if (this.dataService.cacheList[cacheKey]) {
+                delete this.dataService.cacheList[cacheKey]['_displayTextLoading'];
+                delete this.dataService.cacheList[cacheKey]['_loadingTriggered'];
+            }
         }
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.8", ngImport: i0, type: MXSelectionValueComponent, deps: null, target: i0.ɵɵFactoryTarget.Injectable }); }
@@ -2215,5 +2450,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.8", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { AXAutoFocusDirective, AXAutocompleteParentComponent, AXButtonClickEvent, AXClearableComponent, AXClickEvent, AXClosableComponent, AXCommonModule, AXComponent, AXComponentCloseEvent, AXComponentClosedPromise, AXComponentClosing, AXComponentResult, AXDataSource, AXDomService, AXEvent, AXFocusEvent, AXFocusableComponent, AXHotkeyDirective, AXHotkeysService, AXHtmlEvent, AXInfiniteScrollerDirective, AXInvertedColorDirective, AXItemClickEvent, AXListDataSource, AXNgModelDelayedValueChangedDirective, AXOptionChangedEvent, AXPagedComponent, AXRangeChangedEvent, AXResponsiveDirective, AXRippleDirective, AXSearchableComponent, AXSelectionValueChangedEvent, AXValuableComponent, AXValueChangedEvent, AX_LOCATIONS, AX_PLACEMENT_BOTTOM, AX_PLACEMENT_BOTTOM_END, AX_PLACEMENT_BOTTOM_START, AX_PLACEMENT_END, AX_PLACEMENT_END_BOTTOM, AX_PLACEMENT_END_TOP, AX_PLACEMENT_MAP, AX_PLACEMENT_START, AX_PLACEMENT_START_BOTTOM, AX_PLACEMENT_START_TOP, AX_PLACEMENT_TOP, AX_PLACEMENT_TOP_END, AX_PLACEMENT_TOP_START, AX_SELECTION_DATA_TOKEN, AX_STYLE_COLOR_TYPES, AX_STYLE_LOOK_TYPES, MXBaseComponent, MXButtonBaseComponent, MXColorComponent, MXColorLookComponent, MXInputBaseValueComponent, MXInteractiveComponent, MXLookComponent, MXLookableComponent, MXSelectionBridgeService, MXSelectionValueComponent, MXValueComponent, NXButtonComponent, NXClickEvent, NXColorComponent, NXComponent, NXEvent, NXInteractiveComponent, NXLookComponent, NXNativeEvent, NXValueComponent, TAB_META_KEY, convertArrayToDataSource, convertToPlacement };
+export { AXAutoFocusDirective, AXAutocompleteParentComponent, AXButtonClickEvent, AXClearableComponent, AXClickEvent, AXClosableComponent, AXCommonModule, AXComponent, AXComponentCloseEvent, AXComponentClosedPromise, AXComponentClosing, AXComponentResult, AXDataSource, AXDomService, AXEvent, AXFocusEvent, AXFocusableComponent, AXHotkeyDirective, AXHotkeysService, AXHtmlEvent, AXInfiniteScrollerDirective, AXInvertedColorDirective, AXItemClickEvent, AXItemSelectedEvent, AXListDataSource, AXNgModelDelayedValueChangedDirective, AXOptionChangedEvent, AXPagedComponent, AXRangeChangedEvent, AXResponsiveDirective, AXRippleDirective, AXSearchableComponent, AXSelectionValueChangedEvent, AXValuableComponent, AXValueChangedEvent, AX_LOCATIONS, AX_PLACEMENT_BOTTOM, AX_PLACEMENT_BOTTOM_END, AX_PLACEMENT_BOTTOM_START, AX_PLACEMENT_END, AX_PLACEMENT_END_BOTTOM, AX_PLACEMENT_END_TOP, AX_PLACEMENT_MAP, AX_PLACEMENT_START, AX_PLACEMENT_START_BOTTOM, AX_PLACEMENT_START_TOP, AX_PLACEMENT_TOP, AX_PLACEMENT_TOP_END, AX_PLACEMENT_TOP_START, AX_SELECTION_DATA_TOKEN, AX_STYLE_COLOR_TYPES, AX_STYLE_LOOK_TYPES, MXBaseComponent, MXButtonBaseComponent, MXColorComponent, MXColorLookComponent, MXInputBaseValueComponent, MXInteractiveComponent, MXLookComponent, MXLookableComponent, MXSelectionBridgeService, MXSelectionValueComponent, MXValueComponent, NXButtonComponent, NXClickEvent, NXColorComponent, NXComponent, NXEvent, NXInteractiveComponent, NXLookComponent, NXNativeEvent, NXValueComponent, TAB_META_KEY, applyDataSourceQuery, convertArrayToDataSource, convertToPlacement };
 //# sourceMappingURL=acorex-cdk-common.mjs.map