@refinitiv-ui/elements 7.10.10-next.1 → 7.11.0

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

@@ -1,3 +1,5 @@
+import { CollectionComposer } from '@refinitiv-ui/utils/collection.js';
+import { TreeNode } from './tree-node.js';
 export var CheckedState;
 (function (CheckedState) {
     CheckedState[CheckedState["CHECKED"] = 1] = "CHECKED";
@@ -17,17 +19,61 @@ export var TreeManagerMode;
 })(TreeManagerMode || (TreeManagerMode = {}));
 export class TreeManager {
     /**
-     * @param composer CollectionComposer to be managed.
-     * @param mode TreeManager mode which is Relational or Independent.
+     * Collection composer used for managing the data
      */
-    constructor(composer, mode = TreeManagerMode.RELATIONAL) {
+    get composer() {
+        return this._composer;
+    }
+    /**
+     * Most of the time, there is no need to create a new instance of Tree Manager manually.
+     * Use the existing instance in components instead.
+     * @param input Items or CollectionComposer to be managed.
+     * @param mode A mode describing how items are managed either relationally or independently.
+     */
+    constructor(input, mode = TreeManagerMode.RELATIONAL) {
         /**
          * Mode (algorithm) the tree manage is using
          */
         this.mode = TreeManagerMode.RELATIONAL;
-        this.composer = composer;
+        /** Cache map of TreeNode improving performance */
+        this.treeNodeCache = new Map();
+        this._composer = input instanceof CollectionComposer ? input : new CollectionComposer(input);
         this.mode = mode;
     }
+    /**
+     * Returns all items as an array of `TreeNode`.
+     * @returns Array of `TreeNode` representing all items
+     */
+    getTreeNodes() {
+        const result = [];
+        for (const item of this.items) {
+            let treeNode = this.treeNodeCache.get(item);
+            if (!treeNode) {
+                treeNode = new TreeNode(item, this);
+                this.treeNodeCache.set(item, treeNode);
+            }
+            result.push(treeNode);
+        }
+        return result;
+    }
+    /**
+     * Returns a `TreeNode` of the original data item.
+     * If the item doesn't exist, returns `null`.
+     * @param item Original data item
+     * @returns `TreeNode` of the original data item or `null`
+     */
+    getTreeNode(item) {
+        let treeNode = this.treeNodeCache.get(item);
+        if (!treeNode) {
+            const existingItems = this._composer.queryItems((_item) => item === _item, Infinity);
+            if (existingItems.length === 0) {
+                return null;
+            }
+            treeNode = new TreeNode(item, this);
+            this.treeNodeCache.set(item, treeNode);
+        }
+        return treeNode;
+    }
     /**
      * Is the manager maintaining parent/child relationships
      */
@@ -38,20 +84,20 @@ export class TreeManager {
      * Returns all items in the tree
      */
     get items() {
-        return this.composer.queryItems(() => true, Infinity);
+        return this._composer.queryItems(() => true, Infinity);
     }
     /**
-     * Return all items which have children
+     * Returns all items with children
      */
     get parentItems() {
         return this.items.filter((item) => this.isItemParent(item));
     }
     /**
-     * Returns all checked items.
+     * Returns all selected items.
      * When managing relationships, this excludes groups/parents from the result.
      */
     get checkedItems() {
-        const items = this.composer.queryItems((item) => {
+        const items = this._composer.queryItems((item) => {
             if (this.manageRelationships && this.isItemParent(item)) {
                 return false;
             }
@@ -65,17 +111,17 @@ export class TreeManager {
     get orderBySelectedAt() {
         // Order by sequential selected timestamp
         return (itemA, itemB) => {
-            const timeA = this.composer.getItemPropertyValue(itemA, 'selectedAt') ?? 0;
-            const timeB = this.composer.getItemPropertyValue(itemB, 'selectedAt') ?? 0;
+            const timeA = this._composer.getItemPropertyValue(itemA, 'selectedAt') ?? 0;
+            const timeB = this._composer.getItemPropertyValue(itemB, 'selectedAt') ?? 0;
             return timeA - timeB;
         };
     }
     /**
-     * Items which should be visibly displayed.
-     * This can be used to render items.
+     * Returns items which their selected state can be changed.
+     * Hidden, disabled or readonly items are not included.
      */
     get editableItems() {
-        const topLevel = this.composer.queryItems(() => true, 0);
+        const topLevel = this._composer.queryItems(() => true, 0);
         return this.getEditableItems(topLevel);
     }
     /**
@@ -95,11 +141,11 @@ export class TreeManager {
         return result;
     }
     /**
-     * Items which should be visibly displayed.
-     * This can be used to render items.
+     * Returns currently displayed items.
+     * Hidden and children of unexpanded items are not included.
      */
     get visibleItems() {
-        const topLevel = this.composer.queryItems(() => true, 0);
+        const topLevel = this._composer.queryItems(() => true, 0);
         return this.getVisibleItems(topLevel);
     }
     /**
@@ -123,7 +169,7 @@ export class TreeManager {
      * @returns `True` if the item is hidden
      */
     isItemHidden(item) {
-        return this.composer.getItemPropertyValue(item, 'hidden') === true;
+        return this._composer.getItemPropertyValue(item, 'hidden') === true;
     }
     /**
      * Is the item checked?
@@ -134,7 +180,7 @@ export class TreeManager {
         if (this.manageRelationships && this.isItemParent(item)) {
             return !this.getItemChildren(item).some((child) => !this.isItemChecked(child));
         }
-        return this.composer.getItemPropertyValue(item, 'selected') === true;
+        return this._composer.getItemPropertyValue(item, 'selected') === true;
     }
     /**
      * Is the item checked indeterminately?
@@ -156,7 +202,7 @@ export class TreeManager {
         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;
+        return this.isItemCheckable(item) && this._composer.getItemPropertyValue(item, 'selected') !== true;
     }
     /**
      * Determines whether the item is checked and can be changed to an unchecked state.
@@ -167,7 +213,7 @@ export class TreeManager {
         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;
+        return this.isItemCheckable(item) && this._composer.getItemPropertyValue(item, 'selected') === true;
     }
     /**
      * Makes an item visible
@@ -175,7 +221,7 @@ export class TreeManager {
      * @returns {void}
      */
     showItem(item) {
-        this.composer.setItemPropertyValue(item, 'hidden', false);
+        this._composer.setItemPropertyValue(item, 'hidden', false);
         this.updateItem(item); // Make sure the item is updated
     }
     /**
@@ -184,7 +230,7 @@ export class TreeManager {
      * @returns {void}
      */
     hideItem(item) {
-        this.composer.setItemPropertyValue(item, 'hidden', true);
+        this._composer.setItemPropertyValue(item, 'hidden', true);
     }
     /**
      * Forces a modification event, so that the renderer can update.
@@ -193,10 +239,12 @@ export class TreeManager {
      */
     forceUpdateOnPath(item) {
         const path = [...this.getItemAncestors(item), item];
-        path.forEach((item) => this.composer.updateItemTimestamp(item));
+        path.forEach((item) => this._composer.updateItemTimestamp(item));
     }
     /**
+     * TODO: find a way to keep `noRelation` of Tree & Tree Select component in-sync
      * Sets the mode (algorithm) the manager should use
+     * @hidden Mode updating doesn't sync back up Tree component.
      * @param mode Tree manager mode
      * @returns {void}
      */
@@ -206,70 +254,73 @@ export class TreeManager {
         this.parentItems.forEach((item) => this.updateItem(item));
     }
     /**
-     * Updates the data item, forcing a render
+     * Requests the item to be rerendered manually.
+     * Typically, this is not required. The render is triggered automatically when item's properties are updated.
      * @param item Original data item
      * @returns {void}
      */
     updateItem(item) {
-        this.composer.updateItemTimestamp(item);
+        this._composer.updateItemTimestamp(item);
     }
     /**
-     * Includes an item as part of the tree.
-     * @param item Item to include
+     * Shows the item.
+     * @hidden `hidden` usage in filterItems of Tree & Tree Select component conflicts with this API
+     * @param item Original data item
      * @returns `True` if the item is newly included
      */
     includeItem(item) {
-        const result = this.composer.unlockItem(item);
+        const result = this._composer.unlockItem(item);
         this.showItem(item); // Item must be unlocked first
         return result;
     }
     /**
-     * Excludes an item as part of the tree.
-     * @param item Item to exclude
+     * Hides the item.
+     * @hidden `hidden` usage in filterItems of Tree & Tree Select component conflicts with this API
+     * @param item Original data item
      * @returns `True` if the item is newly excluded
      */
     excludeItem(item) {
         this.hideItem(item);
-        return this.composer.lockItem(item);
+        return this._composer.lockItem(item);
     }
     /**
-     * Is the item checkable?
+     * Returns whether the selected state of item can be changed or not.
      * @param item Original data item
      * @returns `True` if the item is not disabled or readonly
      */
     isItemCheckable(item) {
-        return (!this.composer.isItemLocked(item) &&
-            this.composer.getItemPropertyValue(item, 'disabled') !== true &&
-            this.composer.getItemPropertyValue(item, 'readonly') !== true);
+        return (!this._composer.isItemLocked(item) &&
+            this._composer.getItemPropertyValue(item, 'disabled') !== true &&
+            this._composer.getItemPropertyValue(item, 'readonly') !== true);
     }
     /**
-     * Is the item expanded?
+     * Returns the current expanded state of the item.
      * @param item Original data item
-     * @returns `True` if the item is expanded and its children should be visible
+     * @returns `True` if the item is currently expanded so its children are visible.
      */
     isItemExpanded(item) {
-        return this.isItemParent(item) && this.composer.getItemPropertyValue(item, 'expanded') === true;
+        return this.isItemParent(item) && this._composer.getItemPropertyValue(item, 'expanded') === true;
     }
     /**
-     * Is the item a parent?
+     * Returns whether the item contains any children or not.
      * @param item Original data item
      * @returns `True` if the item has children
      */
     isItemParent(item) {
-        return this.composer.isItemParent(item);
+        return this._composer.isItemParent(item);
     }
     /**
-     * Is the item a child?
+     * Returns whether the item has a parent or not.
      * @param item Original data item
      * @returns `True` if the item has a parent
      */
     isItemChild(item) {
-        return this.composer.isItemChild(item);
+        return this._composer.isItemChild(item);
     }
     /**
-     * Calculates the checked stated of the item
+     * Return checked state of the item.
      * @param item Original data item
-     * @returns Checked state of the item
+     * @returns item checked state: CHECKED (1), UNCHECKED (0), INDETERMINATE (-1)
      */
     getItemCheckedState(item) {
         if (this.isItemChecked(item)) {
@@ -281,74 +332,74 @@ export class TreeManager {
         return CheckedState.UNCHECKED;
     }
     /**
-     * Gets an item's ancestors
+     * Returns all ancestors of the item.
      * @param item Original data item
-     * @returns A list of ancestors
+     * @returns An array of ancestors
      */
     getItemAncestors(item) {
-        return this.composer.getItemAncestors(item);
+        return this._composer.getItemAncestors(item);
     }
     /**
-     * Gets an item's descendants
+     * Returns all descendants of the item.
      * @param item Original data item
-     * @param depth Depth to retrieve
-     * @returns A list of descendants
+     * @param depth Depth of descendants to get. If it's `undefined`, get all descendants.
+     * @returns An array of descendants
      */
     getItemDescendants(item, depth) {
-        return this.composer.getItemDescendants(item, depth);
+        return this._composer.getItemDescendants(item, depth);
     }
     /**
-     * Gets an item's parent, if it has one.
+     * Returns the parent of the item, if it has one.
      * @param item Original data item
      * @returns Item parent or `null`
      */
     getItemParent(item) {
-        return this.composer.getItemParent(item);
+        return this._composer.getItemParent(item);
     }
     /**
-     * Gets an item's child collection
+     * Returns the children of the item as an array.
      * @param item Original data item
-     * @returns A list of children
+     * @returns An array of children
      */
     getItemChildren(item) {
-        return this.composer.getItemChildren(item);
+        return this._composer.getItemChildren(item);
     }
     /**
-     * Expand an item to show its children
+     * Expands the item to show its children.
      * @param item Original data item
      * @returns {void}
      */
     expandItem(item) {
         if (this.isItemParent(item)) {
-            this.composer.setItemPropertyValue(item, 'expanded', true);
+            this._composer.setItemPropertyValue(item, 'expanded', true);
         }
     }
     /**
-     * Collapse an item to hide its children
+     * Collapses the item to hide its children.
      * @param item Original data item
      * @returns {void}
      */
     collapseItem(item) {
         if (this.isItemParent(item)) {
-            this.composer.setItemPropertyValue(item, 'expanded', false);
+            this._composer.setItemPropertyValue(item, 'expanded', false);
         }
     }
     /**
-     * Expands all items in the tree
+     * Expands all items.
      * @returns {void}
      */
     expandAllItems() {
         this.parentItems.forEach((item) => this.expandItem(item));
     }
     /**
-     * Collapses all items in the tree
+     * Collapses all items.
      * @returns {void}
      */
     collapseAllItems() {
         this.parentItems.forEach((item) => this.collapseItem(item));
     }
     /**
-     * Checks the item
+     * Selects the item.
      * @param item Original data item
      * @returns `True` if the item is modified
      */
@@ -362,8 +413,8 @@ export class TreeManager {
             this.lastSelectedAt =
                 this.lastSelectedAt && this.lastSelectedAt >= timestamp ? this.lastSelectedAt + 1 : timestamp;
             // Set item selected with timestamp
-            this.composer.setItemPropertyValue(item, 'selected', true);
-            this.composer.setItemPropertyValue(item, 'selectedAt', this.lastSelectedAt);
+            this._composer.setItemPropertyValue(item, 'selected', true);
+            this._composer.setItemPropertyValue(item, 'selectedAt', this.lastSelectedAt);
             if (manageRelationships) {
                 this.forceUpdateOnPath(item);
                 this.getItemDescendants(item).forEach((descendant) => this._checkItem(descendant, false));
@@ -373,7 +424,7 @@ export class TreeManager {
         return false;
     }
     /**
-     * Unchecks the item
+     * Deselects the item.
      * @param item Original data item
      * @returns `True` if the item is modified
      */
@@ -382,7 +433,7 @@ export class TreeManager {
     }
     _uncheckItem(item, manageRelationships = this.manageRelationships) {
         if (this.canUncheckItem(item)) {
-            this.composer.setItemPropertyValue(item, 'selected', false);
+            this._composer.setItemPropertyValue(item, 'selected', false);
             if (manageRelationships) {
                 this.forceUpdateOnPath(item);
                 this.getItemDescendants(item).forEach((descendant) => this._uncheckItem(descendant, false));
@@ -393,27 +444,27 @@ export class TreeManager {
         return false;
     }
     /**
-     * Toggles the item checked state
+     * Toggle the selected state of the item.
      * @param item Original data item
-     * @returns `True` if the item is modified
+     * @returns `true` if the item is modified successfully.
      */
     toggleItem(item) {
         return this.checkItem(item) || this.uncheckItem(item);
     }
     /**
-     * Checks all items
+     * Selects all items.
      * @returns {void}
      */
     checkAllItems() {
         this.editableItems.forEach((item) => this.checkItem(item));
     }
     /**
-     * Unchecks all items
+     * Deselects all items.
      * @returns {void}
      */
     uncheckAllItems() {
         // uncheck items from top levels when manage relationships to avoid redundant re-renders
-        const items = this.manageRelationships ? this.composer.queryItems(() => true, 0) : this.checkedItems;
+        const items = this.manageRelationships ? this._composer.queryItems(() => true, 0) : this.checkedItems;
         items.forEach((item) => this.uncheckItem(item));
     }
 }

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

@@ -0,0 +1,141 @@
+import type { TreeDataItem } from '../helpers/types';
+import { CheckedState, TreeManager } from './tree-manager.js';
+/**
+ * `TreeNode` is expected to be used with `TreeManager` in tandem with Tree & Tree Select components.
+ * Accordingly, only accessors for `TreeDataItem`'s properties are implemented.
+ */
+export declare class TreeNode<T extends TreeDataItem = TreeDataItem> {
+    /** An item managed by Tree Node */
+    protected item: T;
+    /** Tree Manager of the item to be managed */
+    protected manager: TreeManager<T>;
+    /**
+     * Create a new Tree Node managing an item & its Tree Manager.
+     * @param item item to be managed
+     * @param manager `TreeManager` of the item to be managed
+     * @hidden this constructor should be used internally & only by `TreeManager`
+     */
+    constructor(item: T, manager: TreeManager<T>);
+    /** Icon to show, when rendering the item. */
+    get icon(): string | undefined;
+    set icon(icon: string | undefined);
+    /** Label to show, when rendering the item. */
+    get label(): string;
+    set label(value: string);
+    /**
+     * Value of the data item.
+     * This is usually the value which is returned,
+     * when the item is selected.
+     */
+    get value(): string;
+    set value(value: string);
+    /**
+     * Sets the item to be readonly.
+     * Read only items cannot be selected by a user.
+     */
+    get readonly(): boolean;
+    set readonly(value: boolean);
+    /**
+     * Sets the highlight state of the item.
+     * This is usually used for navigating over items,
+     * without affecting focus or multiple item selection.
+     */
+    get highlighted(): boolean;
+    set highlighted(value: boolean);
+    /**
+     * Sets the item to be disabled.
+     * This completely prevents the item from being interacted with.
+     */
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    /**
+     * Whether to show or hide the item from the renderer.
+     * @readonly
+     */
+    get hidden(): boolean;
+    /** Expanded state of child items. If `true`, child items will be visible. */
+    get expanded(): boolean;
+    set expanded(value: boolean);
+    /**
+     * Timestamp indicating the order of sequential selection.
+     * @readonly
+     */
+    get selectedAt(): number | undefined;
+    /**
+     * Selection state of the item.
+     * If its `TreeManager` is in relationship mode, value would be get/set hierarchically.
+     * For instance, items with children would be considered selected when all children are selected.
+     *
+     * For indeterminate state support, use `getCheckedState()` instead.
+     */
+    get selected(): boolean;
+    set selected(value: boolean);
+    /**
+     * Return checked state of the item.
+     * Apart from checked & unchecked state of `selected` accessor,
+     * this method supports indeterminate state for items that some but not all of their children are selected.
+     * @returns item checked state: CHECKED (1), UNCHECKED (0), INDETERMINATE (-1)
+     */
+    getCheckedState(): CheckedState;
+    /**
+     * Returns all ancestors of the item.
+     * @returns An array of ancestors as Tree Node
+     */
+    getAncestors(): TreeNode<T>[];
+    /**
+     * Returns the children of the item.
+     * @returns An array of children as Tree Node
+     */
+    getChildren(): TreeNode<T>[];
+    /**
+     * Returns all descendants of the item.
+     * @param depth Depth of descendants to get. If it's `undefined`, get all descendants.
+     * @returns An array of descendants as Tree Node
+     */
+    getDescendants(depth?: number): TreeNode<T>[];
+    /**
+     * Returns the parent of the item, if it has one.
+     * @returns Item parent as Tree Node or `null`
+     */
+    getParent(): TreeNode<T> | null;
+    /**
+     * Returns whether the selected state of the item can be changed or not.
+     * @returns `True` if the item is not disabled or readonly
+     */
+    isSelectable(): boolean;
+    /**
+     * Returns whether the item contains any children or not.
+     * @returns `True` if the item has children
+     */
+    isParent(): boolean;
+    /**
+     * Returns whether the item has a parent or not.
+     * @returns `True` if the item has a parent
+     */
+    isChild(): boolean;
+    /**
+     * Return the depth of the item starting from 0 for root items,
+     * 1 for children of root items, 2 for grandchildren of root items and so on.
+     * @returns depth of the item
+     */
+    getDepth(): number;
+    /**
+     * Requests the item to be rerendered manually.
+     * Typically, this is not required. The render is triggered automatically when item's properties are updated.
+     * @returns {void}
+     */
+    rerender(): void;
+    /**
+     * Retrieve a value of the specified property.
+     * @param prop property key
+     * @returns property value
+     */
+    private getPropertyValue;
+    /**
+     * Set a value of the specified property.
+     * @param prop property key
+     * @param value property value
+     * @returns {void}
+     */
+    private setProperty;
+}