@acorex/cdk 20.1.20 → 20.1.21

package/fesm2022/acorex-cdk-common.mjs

@@ -1621,9 +1621,14 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.3", ngImpor
             type: Injectable
         }] });
 
+/**
+ * Service that manages selection state and caching for selection components
+ */
 class MXSelectionBridgeService {
     constructor() {
+        /** Array of currently selected items */
         this.selectedItems = [];
+        /** Cache for normalized items keyed by their unique identifier */
         this.cacheList = {};
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.3", ngImport: i0, type: MXSelectionBridgeService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
@@ -1632,209 +1637,352 @@ class MXSelectionBridgeService {
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.3", ngImport: i0, type: MXSelectionBridgeService, decorators: [{
             type: Injectable
         }] });
+/**
+ * Injection token for the selection bridge service
+ */
 const AX_SELECTION_DATA_TOKEN = new InjectionToken('AX_SELECTION_DATA_TOKEN');
+/**
+ * Abstract base component for selection-based value components
+ * Provides common functionality for components that support item selection
+ */
 class MXSelectionValueComponent extends MXValueComponent {
     constructor() {
         super(...arguments);
+        // #region Services
         this.formatService = inject(AXFormatService);
         this.dataService = inject(AX_SELECTION_DATA_TOKEN);
+        // #region Field Configuration Properties
         this._valueField = 'id';
-        this._textTemplate = '';
         this._textField = 'text';
+        this._textTemplate = '';
         this._disabledField = 'disabled';
         this._multiple = false;
     }
+    /** Field name used to extract the unique value from items */
     get valueField() {
         return this._valueField;
     }
-    set valueField(v) {
-        this.setOption({
-            name: 'valueField',
-            value: v,
-        });
-    }
-    get textTemplate() {
-        return this._textTemplate;
-    }
-    set textTemplate(v) {
-        this.setOption({
-            name: 'textTemplate',
-            value: v,
-        });
+    set valueField(value) {
+        this.setOption({ name: 'valueField', value });
     }
+    /** Field name used to extract the display text from items */
     get textField() {
         return this._textField;
     }
-    set textField(v) {
-        this.setOption({
-            name: 'textField',
-            value: v,
-        });
+    set textField(value) {
+        this.setOption({ name: 'textField', value });
     }
+    /** Template string for formatting item display text */
+    get textTemplate() {
+        return this._textTemplate;
+    }
+    set textTemplate(value) {
+        this.setOption({ name: 'textTemplate', value });
+    }
+    /** Field name used to determine if an item is disabled */
     get disabledField() {
         return this._disabledField;
     }
-    set disabledField(v) {
-        this.setOption({
-            name: 'disabledField',
-            value: v,
-        });
+    set disabledField(value) {
+        this.setOption({ name: 'disabledField', value });
     }
+    /** Whether multiple items can be selected */
     get multiple() {
         return this._multiple;
     }
-    set multiple(v) {
+    set multiple(value) {
         this.setOption({
             name: 'multiple',
-            value: v,
-            afterCallback: () => {
-                this.reset(false);
-            },
+            value,
+            afterCallback: () => this.reset(false),
         });
     }
+    // #endregion
+    // #region Computed Properties
+    /** Gets the currently selected items */
     get selectedItems() {
         return this.dataService.selectedItems || [];
     }
+    // #endregion
+    // #region Override Methods
+    /**
+     * Internal method to set and normalize the component value
+     * @param value The value to set (can be single item or array)
+     * @returns Normalized value based on multiple selection mode
+     */
     internalSetValue(value) {
         const isArray = Array.isArray(value);
-        if (value == null || (isArray && value.length == 0)) {
+        // Handle null/empty values
+        if (value == null || (isArray && value.length === 0)) {
             return this.multiple ? [] : null;
         }
-        const normalizedItems = isArray ? this.normalizeItemsList(value, true) : this.normalizeItemsList([value], true);
-        if (normalizedItems.length == 0) {
+        // Normalize items and find by key if needed
+        const itemsToNormalize = isArray ? value : [value];
+        const normalizedItems = this.normalizeItemsList(itemsToNormalize, true);
+        if (normalizedItems.length === 0) {
             return this.multiple ? [] : null;
         }
-        const result = this.multiple ? normalizedItems.map((c) => c[this.valueField]) : normalizedItems[0][this.valueField];
-        return result;
+        // Extract values based on selection mode
+        return this.multiple
+            ? normalizedItems.map(item => item[this.valueField])
+            : normalizedItems[0]?.[this.valueField] ?? null;
     }
+    /**
+     * Override to normalize selected items when value changes
+     */
     emitOnValueChangedEvent(oldValue, newValue) {
         this._normalizeSelectedItems();
         super.emitOnValueChangedEvent(oldValue, newValue);
     }
-    normalizeItemsList(items, findBykey = false) {
-        if (items == null)
+    // #endregion
+    // #region Private Normalization Methods
+    /**
+     * Normalizes a list of items, filtering out null values
+     * @param items Array of items to normalize
+     * @param findByKey Whether to attempt finding items by key
+     * @returns Array of normalized items
+     */
+    normalizeItemsList(items, findByKey = false) {
+        if (!items?.length)
             return [];
-        return items.filter((c) => c != null).map((i) => this.normalizeItem(i, findBykey));
+        return items
+            .filter(item => item != null)
+            .map(item => this.normalizeItem(item, findByKey));
     }
-    normalizeItem(item, findBykey = false) {
-        const complex = typeof item == 'object';
-        const key = complex ? item[this.valueField] : `${item}`;
-        const cacheKey = `k-${key}`;
-        const hasText = !complex || item[this.textField] != null;
-        //
-        if (this.dataService.cacheList[cacheKey] && this.dataService.cacheList[cacheKey][this.textField])
-            return this.dataService.cacheList[cacheKey];
-        //
-        const obj = {};
-        if (complex && hasText) {
-            Object.assign(obj, item);
+    /**
+     * Normalizes a single item, handling caching and async loading
+     * @param item Item to normalize
+     * @param findByKey Whether to attempt finding the item by key
+     * @returns Normalized item object
+     */
+    normalizeItem(item, findByKey = false) {
+        const isComplexObject = typeof item === 'object' && item !== null;
+        const itemRecord = item;
+        const key = isComplexObject ? String(itemRecord[this.valueField]) : 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]) {
+            return cachedItem;
+        }
+        const hasTextProperty = !isComplexObject || itemRecord[this.textField] != null;
+        const normalizedObj = {};
+        if (isComplexObject && hasTextProperty) {
+            // Item already has all required properties
+            Object.assign(normalizedObj, item);
         }
         else {
-            const existsItem = findBykey ? this.getItemByKey(key) : null;
-            if (existsItem && existsItem instanceof Promise) {
-                obj[this.valueField] = key;
-                obj['isLoading'] = true;
-                obj[this.textField] = 'Loading';
-                //
-                existsItem
-                    .then((r) => {
-                    if (typeof r === 'object' && r) {
-                        // obj[this.valueField] = r[this.valueField];
-                        // obj[this.textField] = r[this.textField];
-                        Object.assign(obj, cloneDeep(r));
-                    }
-                    else {
-                        obj[this.valueField] = r || key;
-                        obj[this.textField] = r;
-                    }
-                })
-                    .finally(() => {
-                    delete obj['isLoading'];
-                    this.dataService.cacheList[cacheKey] = obj;
-                    this.cdr.markForCheck();
-                });
-            }
-            else if (existsItem) {
-                obj[this.valueField] = complex ? existsItem[this.valueField] : existsItem;
-                obj[this.textField] = complex ? existsItem[this.textField] : existsItem;
+            // Need to find or create item properties
+            this.handleItemNormalization(normalizedObj, item, key, findByKey, cacheKey);
+        }
+        this.dataService.cacheList[cacheKey] = normalizedObj;
+        return normalizedObj;
+    }
+    /**
+     * Handles the normalization logic for items that need property assignment
+     */
+    handleItemNormalization(normalizedObj, originalItem, key, findByKey, cacheKey) {
+        const existingItem = findByKey ? this.getItemByKey(key) : null;
+        if (existingItem instanceof Promise) {
+            this.handleAsyncItem(normalizedObj, key, existingItem, cacheKey);
+        }
+        else if (existingItem) {
+            this.assignItemProperties(normalizedObj, existingItem, true);
+        }
+        else {
+            this.assignItemProperties(normalizedObj, originalItem, false);
+        }
+    }
+    /**
+     * Handles async item loading with loading state
+     */
+    handleAsyncItem(obj, key, promise, cacheKey) {
+        // Set loading state
+        obj[this.valueField] = key;
+        obj['isLoading'] = true;
+        obj[this.textField] = 'Loading';
+        promise
+            .then(result => {
+            if (typeof result === 'object' && result) {
+                Object.assign(obj, cloneDeep(result));
             }
             else {
-                obj[this.valueField] = complex ? item[this.valueField] : item;
-                obj[this.textField] = complex ? item[this.textField] : item;
+                obj[this.valueField] = result || key;
+                obj[this.textField] = result;
             }
+        })
+            .finally(() => {
+            delete obj['isLoading'];
+            this.dataService.cacheList[cacheKey] = obj;
+            this.cdr.markForCheck();
+        });
+    }
+    /**
+     * Assigns value and text properties to the normalized object
+     */
+    assignItemProperties(obj, sourceItem, isComplexSource) {
+        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];
         }
-        this.dataService.cacheList[cacheKey] = obj;
-        return obj;
+        else {
+            obj[this.valueField] = isSourceObject ? sourceRecord[this.valueField] : sourceItem;
+            obj[this.textField] = isSourceObject ? sourceRecord[this.textField] : sourceItem;
+        }
+    }
+    /**
+     * Creates a consistent cache key for an item
+     */
+    createCacheKey(key) {
+        return `k-${key}`;
     }
+    /**
+     * 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((v) => this.normalizeItem(v));
+        const values = Array.isArray(this.value)
+            ? this.value
+            : this.value != null ? [this.value] : [];
+        this.dataService.selectedItems = values.map(value => this.normalizeItem(value));
     }
+    // #endregion
+    // #region Public Selection Methods
+    /**
+     * Unselects the specified items from the selection
+     * @param items Items to unselect
+     */
     unselectItems(...items) {
-        if (!items || items.length === 0) {
+        if (!items?.length) {
             this.commitValue([], true);
             return;
         }
-        const normalizeItems = Array.isArray(items) ? this.normalizeItemsList(items) : [this.normalizeItem(items)];
-        const newSelectedItems = this.selectedItems.filter((i) => !normalizeItems.some((n) => n[this.valueField] == i[this.valueField]));
+        const normalizedItems = this.normalizeItemsList(items);
+        const newSelectedItems = this.selectedItems.filter(selectedItem => !normalizedItems.some(normalizedItem => normalizedItem[this.valueField] === selectedItem[this.valueField]));
         this.commitValue(newSelectedItems, true);
     }
+    /**
+     * Selects the specified items
+     * @param items Items to select
+     */
     selectItems(...items) {
-        if (items && items.length) {
-            let newSelectedItems = Array.isArray(this.value) ? this.value : [this.value];
-            const normalizeItems = Array.isArray(items) ? this.normalizeItemsList(items) : [this.normalizeItem(items)];
-            if (this.multiple) {
-                newSelectedItems = [...newSelectedItems, ...normalizeItems];
-            }
-            else {
-                newSelectedItems = normalizeItems;
-            }
-            this.commitValue(newSelectedItems, true);
-        }
+        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.commitValue(newSelectedItems, true);
     }
+    /**
+     * Toggles the selection state of the specified items
+     * @param items Items to toggle
+     */
     toggleSelect(...items) {
-        items?.forEach((item) => {
+        items?.forEach(item => {
             if (this.multiple) {
-                this.isItemSelected(item) ? this.unselectItems(item) : this.selectItems(item);
+                this.isItemSelected(item)
+                    ? this.unselectItems(item)
+                    : this.selectItems(item);
             }
             else {
                 this.selectItems(item);
             }
         });
     }
+    // #endregion
+    // #region Public Utility Methods
+    /**
+     * Checks if an item is currently selected
+     * @param item Item to check
+     * @returns True if the item is selected
+     */
     isItemSelected(item) {
-        return this.selectedItems.some((c) => c[this.valueField] === this.normalizeItem(item)[this.valueField]);
+        const normalizedItem = this.normalizeItem(item);
+        return this.selectedItems.some(selectedItem => selectedItem[this.valueField] === normalizedItem[this.valueField]);
     }
+    /**
+     * Checks if an item is disabled
+     * @param item Item to check
+     * @returns True if the item is disabled
+     */
     isItemDisabled(item) {
+        const itemRecord = item;
         return (this.disabled ||
-            coerceBooleanProperty(item[this.disabledField]) === true ||
-            (this.disabledCallback ? this.disabledCallback({ item, index: -1 }) : false));
+            coerceBooleanProperty(itemRecord[this.disabledField]) === true ||
+            (this.disabledCallback?.({ item, index: -1 }) ?? false));
     }
-    // protected getDisplayText(item: T) {
-    //   const normalizeItem = this.normalizeItem(item) as any;
-    //   return formattedText || normalizeItem[this.valueField];
-    // }
+    // #endregion
+    // #region Protected Utility Methods
+    /**
+     * Gets the display text for an item using template or text field
+     * @param item Item to get display text for
+     * @returns Formatted display text
+     */
     getDisplayText(item) {
-        const normalizeItem = this.normalizeItem(item);
-        const formattedTemplate = this.formatService.format(this.textTemplate, 'string', normalizeItem);
-        if (this.textTemplate && formattedTemplate != this.textTemplate)
-            return formattedTemplate;
-        else
-            return normalizeItem[this.textField] || normalizeItem[this.valueField];
+        const normalizedItem = this.normalizeItem(item);
+        // Try template formatting first
+        if (this.textTemplate) {
+            const formattedTemplate = this.formatService.format(this.textTemplate, 'string', normalizedItem);
+            if (formattedTemplate !== this.textTemplate) {
+                return formattedTemplate;
+            }
+        }
+        // Use text field or fallback to value field
+        if (normalizedItem[this.textField]) {
+            return String(normalizedItem[this.textField]);
+        }
+        // Attempt to load item by key if text is missing
+        const value = normalizedItem[this.valueField];
+        this.loadAndCacheItemByKey(value);
+        return String(value);
     }
+    /**
+     * Gets the value of an item
+     * @param item Item to get value from
+     * @returns Item value
+     */
     getValue(item) {
-        const normalizeItem = this.normalizeItem(item);
-        return normalizeItem[this.valueField];
+        const normalizedItem = this.normalizeItem(item);
+        return normalizedItem[this.valueField];
     }
+    /**
+     * Clears the selection cache and selected items
+     */
     clearSelectionCache() {
         this.dataService.cacheList = {};
         this.dataService.selectedItems = [];
         this.cdr.markForCheck();
     }
+    /**
+     * Clears only the cache while preserving selected items
+     */
     softClearSelectionCache() {
         this.dataService.cacheList = {};
         this.cdr.markForCheck();
     }
+    // #endregion
+    // #region Private Helper Methods
+    /**
+     * Asynchronously loads an item by its key and caches the result
+     * @param key Key to load item by
+     */
+    async loadAndCacheItemByKey(key) {
+        try {
+            const item = await this.getItemByKey(key);
+            if (item) {
+                const normalizedItem = this.normalizeItem(item);
+                const cacheKey = this.createCacheKey(String(normalizedItem[this.valueField]));
+                this.dataService.cacheList[cacheKey] = normalizedItem;
+                this.cdr.markForCheck();
+            }
+        }
+        catch (error) {
+            console.warn('Failed to load item by key:', key, error);
+        }
+    }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.3", ngImport: i0, type: MXSelectionValueComponent, deps: null, target: i0.ɵɵFactoryTarget.Injectable }); }
     static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.1.3", ngImport: i0, type: MXSelectionValueComponent }); }
 }