@refinitiv-ui/elements 5.3.4 → 5.8.0

package/lib/tree/elements/tree-item.d.ts

@@ -1,9 +1,9 @@
 import { JSXInterface } from '../../jsx';
 import { TemplateResult, ControlElement, PropertyValues } from '@refinitiv-ui/core';
-import '../../icon';
-import '../../checkbox';
-import { TreeDataItem } from '../helpers/types';
-import { CheckedState } from '../managers/tree-manager';
+import '../../icon/index.js';
+import '../../checkbox/index.js';
+import type { TreeDataItem } from '../helpers/types';
+import { CheckedState } from '../managers/tree-manager.js';
 /**
  * Displays a tree list item.
  * Groups display expansion arrows.

package/lib/tree/elements/tree-item.js

@@ -1,15 +1,12 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { customElement, html, property, ControlElement } from '@refinitiv-ui/core';
-import '../../icon';
-import { preload } from '../../icon';
-import '../../checkbox';
-import { CheckedState } from '../managers/tree-manager';
-import { VERSION } from '../../';
+import { __decorate } from "tslib";
+import { html, ControlElement } from '@refinitiv-ui/core';
+import { customElement } from '@refinitiv-ui/core/lib/decorators/custom-element.js';
+import { property } from '@refinitiv-ui/core/lib/decorators/property.js';
+import { VERSION } from '../../version.js';
+import '../../icon/index.js';
+import { preload } from '../../icon/index.js';
+import '../../checkbox/index.js';
+import { CheckedState } from '../managers/tree-manager.js';
 preload('right');
 const emptyTemplate = html ``;
 /**
@@ -106,7 +103,7 @@ let TreeItem = class TreeItem extends ControlElement {
         if (typeof this.icon === 'undefined') {
             return emptyTemplate;
         }
-        return html `<ef-icon part="label-icon" src="${this.icon}"></ef-icon>`;
+        return html `<ef-icon part="label-icon" icon="${this.icon}"></ef-icon>`;
     }
     /**
      * Is the item fully checked?

package/lib/tree/elements/tree.d.ts

@@ -1,10 +1,10 @@
 import { JSXInterface } from '../../jsx';
 import { PropertyValues, TapEvent } from '@refinitiv-ui/core';
-import { CollectionComposer } from '@refinitiv-ui/utils';
-import { List } from '../../list';
-import { TreeRenderer } from '../helpers/renderer';
-import { TreeData, TreeDataItem } from '../helpers/types';
-import { TreeManagerMode } from '../managers/tree-manager';
+import { CollectionComposer } from '@refinitiv-ui/utils/lib/collection.js';
+import { List } from '../../list/index.js';
+import { TreeRenderer } from '../helpers/renderer.js';
+import type { TreeData, TreeDataItem, TreeFilter } from '../helpers/types';
+import { TreeManagerMode } from '../managers/tree-manager.js';
 /**
  * Displays a tree structure
  * to be used for menus and group selections
@@ -35,6 +35,16 @@ export declare class Tree<T extends TreeDataItem = TreeDataItem> extends List<T>
      * selection mode is enabled
      */
     noRelation: boolean;
+    /**
+     * Query string applied to tree
+     */
+    query: string;
+    /**
+     * Custom filter for static data
+     * @type {TreeFilter<T> | null}
+     * @ignore set to protected for now and need to discuss before set to public API
+     */
+    protected filter: TreeFilter<T> | null;
     /**
      * Renderer used for generating tree items
      * @type {TreeRenderer}
@@ -117,10 +127,46 @@ export declare class Tree<T extends TreeDataItem = TreeDataItem> extends List<T>
      * @override
      */
     protected update(changedProperties: PropertyValues): void;
+    /**
+     * Filter the internal items by query changes items' hidden state
+     * @returns {void}
+     */
+    protected filterItems(): void;
+    /**
+     * Utility method
+     * Adds descendants for each item passed
+     * @param items List of child items
+     * @returns {void}
+     */
+    protected addItemDescendantsToRender(items: T[]): void;
+    /**
+     * Utility method
+     * Add nested children of item list
+     * @param items List of items
+     * @param excludeItems List of exclude items
+     * @param [includeHidden=false] Include hidden items
+     * @returns {void}
+     */
+    protected addNestedItemsToRender(items: readonly T[], excludeItems: readonly T[], includeHidden?: boolean): void;
+    /**
+     * Utility method
+     * Adds ancestors for each item passed and expand
+     * @param items List of child items
+     * @returns {void}
+     */
+    protected addExpandedAncestorsToRender(items: T[]): void;
+    /**
+     * Utility method
+     * Adds parent and expands
+     * @param ancestor parent item
+     * @returns {void}
+     */
+    protected addExpandedAncestorToRender(ancestor: T): void;
     /**
      * Selected items in tree
      * @override
      * @type {string[]}
+     * @default []
      */
     get values(): string[];
     set values(value: string[]);

package/lib/tree/elements/tree.js

@@ -1,14 +1,11 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { customElement, property } from '@refinitiv-ui/core';
-import { VERSION } from '../../';
-import { List } from '../../list';
-import { TreeRenderer } from '../helpers/renderer';
-import { TreeManager, TreeManagerMode } from '../managers/tree-manager';
+import { __decorate } from "tslib";
+import { customElement } from '@refinitiv-ui/core/lib/decorators/custom-element.js';
+import { property } from '@refinitiv-ui/core/lib/decorators/property.js';
+import { VERSION } from '../../version.js';
+import { List } from '../../list/index.js';
+import { TreeRenderer } from '../helpers/renderer.js';
+import { defaultFilter } from '../helpers/filter.js';
+import { TreeManager, TreeManagerMode } from '../managers/tree-manager.js';
 const EXPAND_TOGGLE_ATTR = 'expand-toggle';
 /**
  * Displays a tree structure
@@ -37,6 +34,16 @@ let Tree = class Tree extends List {
          * selection mode is enabled
          */
         this.noRelation = false;
+        /**
+         * Query string applied to tree
+         */
+        this.query = '';
+        /**
+         * Custom filter for static data
+         * @type {TreeFilter<T> | null}
+         * @ignore set to protected for now and need to discuss before set to public API
+         */
+        this.filter = defaultFilter(this);
         /**
          * Renderer used for generating tree items
          * @type {TreeRenderer}
@@ -230,12 +237,129 @@ let Tree = class Tree extends List {
         if (changedProperties.has('noRelation') || changedProperties.has('multiple')) {
             this.manager.setMode(this.mode);
         }
+        if (changedProperties.has('query') || changedProperties.has('data')) {
+            this.filterItems();
+        }
         super.update(changedProperties);
     }
+    /**
+     * Filter the internal items by query changes items' hidden state
+     * @returns {void}
+     */
+    filterItems() {
+        // if filter is null, it is off and external app is responsible
+        if (this.filter) {
+            const filter = this.filter;
+            const items = this.queryItems((item) => {
+                // Do not filter hidden items
+                if (item.hidden) {
+                    return false;
+                }
+                const result = filter(item);
+                if (result) {
+                    this.manager.includeItem(item);
+                }
+                else {
+                    this.manager.excludeItem(item);
+                }
+                return result;
+            }).slice();
+            // Do not expand tree if there is no filter applied
+            if (this.query) {
+                /**
+                 * Add all descendants of item list to make the descendants
+                 * are accessible which user can navigate into the nested data
+                 */
+                this.addItemDescendantsToRender(items);
+                /**
+                 * Add all parents of item list which they must be shown
+                 * when some descendant is shown.
+                 */
+                this.addExpandedAncestorsToRender(items);
+            }
+        }
+    }
+    /**
+     * Utility method
+     * Adds descendants for each item passed
+     * @param items List of child items
+     * @returns {void}
+     */
+    addItemDescendantsToRender(items) {
+        items.forEach((item) => {
+            /**
+             * Collapse an item to prevent tree show too many nested expanded
+             */
+            if (this.manager.isItemExpanded(item)) {
+                this.manager.collapseItem(item);
+            }
+            /**
+             * show all descendants of items to make them all are selectable
+             * and user can navigate into nested data
+             */
+            const children = this.composer.getItemChildren(item);
+            if (children.length) {
+                this.addNestedItemsToRender(children, items, false);
+            }
+        });
+    }
+    /**
+     * Utility method
+     * Add nested children of item list
+     * @param items List of items
+     * @param excludeItems List of exclude items
+     * @param [includeHidden=false] Include hidden items
+     * @returns {void}
+     */
+    addNestedItemsToRender(items, excludeItems, includeHidden = false) {
+        items.forEach(item => {
+            // Skip hidden and exclude item
+            if (!item.hidden && !excludeItems.includes(item)) {
+                // Add item and nested children
+                this.manager.includeItem(item);
+                const children = this.manager.getItemChildren(item);
+                if (children.length) {
+                    this.addNestedItemsToRender(children, excludeItems, includeHidden);
+                }
+            }
+        });
+    }
+    /**
+     * Utility method
+     * Adds ancestors for each item passed and expand
+     * @param items List of child items
+     * @returns {void}
+     */
+    addExpandedAncestorsToRender(items) {
+        // Establish unique ancestors set
+        const ancestors = new Set();
+        // we iterate each item match so as to find ancestors
+        items.forEach((item) => {
+            // Get the ancestors
+            const parent = this.manager.getItemParent(item);
+            if (parent && !ancestors.has(parent)) {
+                this.manager.getItemAncestors(item).forEach((ancestor) => {
+                    ancestors.add(ancestor); // track ancestors
+                    this.addExpandedAncestorToRender(ancestor);
+                });
+            }
+        });
+    }
+    /**
+     * Utility method
+     * Adds parent and expands
+     * @param ancestor parent item
+     * @returns {void}
+     */
+    addExpandedAncestorToRender(ancestor) {
+        this.manager.includeItem(ancestor);
+        this.manager.expandItem(ancestor);
+    }
     /**
      * Selected items in tree
      * @override
      * @type {string[]}
+     * @default []
      */
     get values() {
         return this.manager.checkedItems.map(item => {
@@ -277,6 +401,9 @@ __decorate([
 __decorate([
     property({ attribute: 'no-relation', type: Boolean })
 ], Tree.prototype, "noRelation", void 0);
+__decorate([
+    property({ type: String })
+], Tree.prototype, "query", void 0);
 __decorate([
     property({ attribute: false })
 ], Tree.prototype, "renderer", void 0);

package/lib/tree/helpers/filter.d.ts

@@ -0,0 +1,8 @@
+import type { Tree, TreeDataItem } from '../index';
+import type { TreeFilter } from './types';
+/**
+ * Default filter used by tree
+ * @param el Tree instance to filter
+ * @returns Filter accepting an item
+ */
+export declare const defaultFilter: <T extends TreeDataItem = TreeDataItem>(el: Tree<T>) => TreeFilter<T>;

package/lib/tree/helpers/filter.js

@@ -0,0 +1,33 @@
+/**
+ * Default filter used by tree
+ * @param el Tree instance to filter
+ * @returns Filter accepting an item
+ */
+export const defaultFilter = (el) => {
+    // reference query string for validating queryRegExp cache state
+    let query = '';
+    // cache RegExp
+    let queryRegExp;
+    // Get current RegExp, or renew if out of date
+    // this is fetched on demand by filter/renderer
+    // only created once per query
+    const getRegularExpressionOfQuery = () => {
+        if (el.query !== query || !queryRegExp) {
+            query = el.query || '';
+            queryRegExp = new RegExp(query.replace(/(\W)/g, '\\$1'), 'i');
+        }
+        return queryRegExp;
+    };
+    // return scoped custom filter
+    return (item) => {
+        const label = item.label;
+        if (!label) {
+            return false;
+        }
+        const regex = getRegularExpressionOfQuery();
+        const result = regex.test(label);
+        // this regex uses global scope, so the index needs resetting
+        regex.lastIndex = 0;
+        return result;
+    };
+};

package/lib/tree/helpers/renderer.d.ts

@@ -1,5 +1,5 @@
-import { Renderer } from '../../list/renderer';
-import '../elements/tree-item';
+import { Renderer } from '../../list/renderer.js';
+import '../elements/tree-item.js';
 export declare class TreeRenderer extends Renderer {
     constructor(scope?: unknown);
 }

package/lib/tree/helpers/renderer.js

@@ -1,6 +1,6 @@
-import { TreeManager, TreeManagerMode, CheckedState } from '../managers/tree-manager';
-import { Renderer } from '../../list/renderer';
-import '../elements/tree-item';
+import { TreeManager, TreeManagerMode, CheckedState } from '../managers/tree-manager.js';
+import { Renderer } from '../../list/renderer.js';
+import '../elements/tree-item.js';
 export class TreeRenderer extends Renderer {
     constructor(scope) {
         let manager;

package/lib/tree/helpers/types.d.ts

@@ -1,4 +1,4 @@
-import { CollectionComposer, DataItem } from '@refinitiv-ui/utils';
+import type { CollectionComposer, DataItem } from '@refinitiv-ui/utils/lib/collection';
 export declare type TreeData<T extends TreeDataItem = TreeDataItem> = T[] | CollectionComposer<T> | null;
 export interface TreeDataItem extends DataItem {
     /**
@@ -15,3 +15,11 @@ export interface TreeDataItem extends DataItem {
      */
     expanded?: boolean;
 }
+/**
+ * Predicate callback
+ * Matches item against filter function
+ *
+ * @param item Item to filter
+ * @return Does item match filter
+ */
+export declare type TreeFilter<T extends TreeDataItem = TreeDataItem> = (item: T) => boolean;

package/lib/tree/index.d.ts

@@ -1,4 +1,4 @@
-export * from './elements/tree';
-export * from './elements/tree-item';
-export { TreeRenderer } from './helpers/renderer';
-export { TreeData, TreeDataItem } from './helpers/types';
+export * from './elements/tree.js';
+export * from './elements/tree-item.js';
+export { TreeRenderer } from './helpers/renderer.js';
+export type { TreeData, TreeDataItem } from './helpers/types';

package/lib/tree/index.js

@@ -1,3 +1,3 @@
-export * from './elements/tree';
-export * from './elements/tree-item';
-export { TreeRenderer } from './helpers/renderer';
+export * from './elements/tree.js';
+export * from './elements/tree-item.js';
+export { TreeRenderer } from './helpers/renderer.js';

package/lib/tree/managers/tree-manager.d.ts

@@ -1,5 +1,5 @@
-import { CollectionComposer } from '@refinitiv-ui/utils';
-import { TreeDataItem } from '../helpers/types';
+import type { CollectionComposer } from '@refinitiv-ui/utils/lib/collection';
+import type { TreeDataItem } from '../helpers/types';
 export declare enum CheckedState {
     CHECKED = 1,
     UNCHECKED = 0,
@@ -72,18 +72,30 @@ export declare class TreeManager<T extends TreeDataItem> {
      * @returns `True` if the item is hidden
      */
     private isItemHidden;
-    /**
-     * Is the item visible?
-     * @param item Original data item
-     * @returns `True` if the item is visible
-     */
-    private isItemVisible;
     /**
      * Is the item checked?
      * @param item Original data item
      * @returns `True` if the item is checked
      */
     private isItemChecked;
+    /**
+     * Is the item checked indeterminately?
+     * @param item Original data item
+     * @returns `True` if the item has managed relationships and contains checked descendants
+     */
+    private isItemCheckedIndeterminate;
+    /**
+     * Determines whether the item is unchecked and can be changed to a checked state.
+     * @param item Original data item
+     * @returns True if the item can be changed to 'checked'.
+     */
+    private canCheckItem;
+    /**
+     * Determines whether the item is checked and can be changed to an unchecked state.
+     * @param item Original data item
+     * @returns True if the item can be changed to 'unchecked'.
+     */
+    private canUncheckItem;
     /**
      * Makes an item visible
      * @param item Original data item
@@ -98,10 +110,10 @@ export declare class TreeManager<T extends TreeDataItem> {
     private hideItem;
     /**
      * Forces a modification event, so that the renderer can update.
-     * @param item Item of which to find ancestors
+     * @param item Item of which to find path
      * @returns {void}
      */
-    private forceUpdateOnAncestors;
+    private forceUpdateOnPath;
     /**
      * Sets the mode (algorithm) the manager should use
      * @param mode Tree manager mode

package/lib/tree/managers/tree-manager.js

@@ -48,7 +48,10 @@ export class TreeManager {
      */
     get checkedItems() {
         return this.composer.queryItems((item) => {
-            return this.isItemChecked(item) && (!this.manageRelationships || !this.getItemChildren(item).length);
+            if (this.manageRelationships && this.isItemParent(item)) {
+                return false;
+            }
+            return this.isItemChecked(item);
         }, Infinity);
     }
     /**
@@ -91,8 +94,7 @@ export class TreeManager {
      */
     getVisibleItems(items, result = []) {
         for (const item of items) {
-            if (this.isItemVisible(item)) {
-                result.push(item);
+            if (!this.isItemHidden(item) && result.push(item) && this.isItemExpanded(item)) {
                 const children = this.getItemChildren(item);
                 children.length && this.getVisibleItems(children, result);
             }
@@ -107,24 +109,50 @@ export class TreeManager {
     isItemHidden(item) {
         return this.composer.getItemPropertyValue(item, 'hidden') === true;
     }
-    /**
-     * Is the item visible?
-     * @param item Original data item
-     * @returns `True` if the item is visible
-     */
-    isItemVisible(item) {
-        return !this.isItemHidden(item)
-            && !this.composer.getItemAncestors(item)
-                .some(ancestor => !this.isItemExpanded(ancestor));
-    }
     /**
      * Is the item checked?
      * @param item Original data item
      * @returns `True` if the item is checked
      */
     isItemChecked(item) {
+        if (this.manageRelationships && this.isItemParent(item)) {
+            return !this.getItemChildren(item).some(child => !this.isItemChecked(child));
+        }
         return this.composer.getItemPropertyValue(item, 'selected') === true;
     }
+    /**
+     * Is the item checked indeterminately?
+     * @param item Original data item
+     * @returns `True` if the item has managed relationships and contains checked descendants
+     */
+    isItemCheckedIndeterminate(item) {
+        if (this.manageRelationships && this.isItemParent(item)) {
+            return this.getItemDescendants(item).some(desc => this.isItemChecked(desc));
+        }
+        return false;
+    }
+    /**
+     * Determines whether the item is unchecked and can be changed to a checked state.
+     * @param item Original data item
+     * @returns True if the item can be changed to 'checked'.
+     */
+    canCheckItem(item) {
+        if (this.manageRelationships && this.isItemParent(item)) {
+            return this.getItemChildren(item).some(child => this.canCheckItem(child));
+        }
+        return this.isItemCheckable(item) && this.composer.getItemPropertyValue(item, 'selected') !== true;
+    }
+    /**
+     * Determines whether the item is checked and can be changed to an unchecked state.
+     * @param item Original data item
+     * @returns True if the item can be changed to 'unchecked'.
+     */
+    canUncheckItem(item) {
+        if (this.manageRelationships && this.isItemParent(item)) {
+            return this.getItemChildren(item).some(child => this.canUncheckItem(child));
+        }
+        return this.isItemCheckable(item) && this.composer.getItemPropertyValue(item, 'selected') === true;
+    }
     /**
      * Makes an item visible
      * @param item Original data item
@@ -144,15 +172,12 @@ export class TreeManager {
     }
     /**
      * Forces a modification event, so that the renderer can update.
-     * @param item Item of which to find ancestors
+     * @param item Item of which to find path
      * @returns {void}
      */
-    forceUpdateOnAncestors(item) {
-        this.composer.getItemAncestors(item).forEach(ancestor => {
-            const allSelected = !this.getItemChildren(ancestor).some(child => this.isItemCheckable(child) && !this.isItemChecked(child));
-            this.composer.setItemPropertyValue(ancestor, 'selected', allSelected);
-            this.updateItem(ancestor);
-        });
+    forceUpdateOnPath(item) {
+        const path = [...this.getItemAncestors(item), item];
+        path.forEach(item => this.composer.updateItemTimestamp(item));
     }
     /**
      * Sets the mode (algorithm) the manager should use
@@ -232,16 +257,13 @@ export class TreeManager {
      * @returns Checked state of the item
      */
     getItemCheckedState(item) {
-        const descendants = this.getItemDescendants(item).filter(descendant => !this.composer.isItemLocked(descendant));
-        const isParent = descendants.length > 0;
-        if (isParent && this.manageRelationships) {
-            const checkedCount = descendants.reduce((count, item) => {
-                return count + (this.isItemChecked(item) === true ? 1 : 0);
-            }, 0);
-            return !checkedCount ? CheckedState.UNCHECKED
-                : checkedCount === descendants.length ? CheckedState.CHECKED : CheckedState.INDETERMINATE;
+        if (this.isItemChecked(item)) {
+            return CheckedState.CHECKED;
         }
-        return this.isItemChecked(item) === true ? CheckedState.CHECKED : CheckedState.UNCHECKED;
+        if (this.isItemCheckedIndeterminate(item)) {
+            return CheckedState.INDETERMINATE;
+        }
+        return CheckedState.UNCHECKED;
     }
     /**
      * Gets an item's ancestors
@@ -319,17 +341,14 @@ export class TreeManager {
         return this._checkItem(item);
     }
     _checkItem(item, manageRelationships = this.manageRelationships) {
-        if (this.isItemCheckable(item) && !this.isItemChecked(item)) {
+        if (this.canCheckItem(item)) {
             this.composer.setItemPropertyValue(item, 'selected', true);
             if (manageRelationships) {
-                this.forceUpdateOnAncestors(item);
+                this.forceUpdateOnPath(item);
                 this.getItemDescendants(item).forEach(descendant => this._checkItem(descendant, false));
             }
             return true;
         }
-        if (this.isItemParent(item)) {
-            this.updateItem(item); // update parent checked state
-        }
         return false;
     }
     /**
@@ -341,17 +360,14 @@ export class TreeManager {
         return this._uncheckItem(item);
     }
     _uncheckItem(item, manageRelationships = this.manageRelationships) {
-        if (this.isItemCheckable(item) && this.isItemChecked(item)) {
+        if (this.canUncheckItem(item)) {
             this.composer.setItemPropertyValue(item, 'selected', false);
             if (manageRelationships) {
-                this.forceUpdateOnAncestors(item);
+                this.forceUpdateOnPath(item);
                 this.getItemDescendants(item).forEach(descendant => this._uncheckItem(descendant, false));
             }
             return true;
         }
-        if (this.isItemParent(item)) {
-            this.updateItem(item); // update parent checked state
-        }
         return false;
     }
     /**
@@ -360,7 +376,7 @@ export class TreeManager {
      * @returns `True` if the item is modified
      */
     toggleItem(item) {
-        return this.isItemChecked(item) ? this.uncheckItem(item) : this.checkItem(item);
+        return this.checkItem(item) || this.uncheckItem(item);
     }
     /**
      * Checks all items