@refinitiv-ui/elements 7.10.10 → 7.11.0

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

@@ -1,5 +1,6 @@
-import type { CollectionComposer } from '@refinitiv-ui/utils/collection.js';
+import { CollectionComposer } from '@refinitiv-ui/utils/collection.js';
 import type { TreeDataItem } from '../helpers/types';
+import { TreeNode } from './tree-node.js';
 export declare enum CheckedState {
     CHECKED = 1,
     UNCHECKED = 0,
@@ -16,10 +17,11 @@ export declare enum TreeManagerMode {
     INDEPENDENT = 0
 }
 export declare class TreeManager<T extends TreeDataItem> {
+    private _composer;
     /**
-     * Internal composer used for managing the data
+     * Collection composer used for managing the data
      */
-    private composer;
+    get composer(): CollectionComposer<T>;
     /**
      * Mode (algorithm) the tree manage is using
      */
@@ -28,11 +30,27 @@ export declare class TreeManager<T extends TreeDataItem> {
      * Last selected item timestamp
      */
     private lastSelectedAt?;
+    /** Cache map of TreeNode improving performance */
+    private treeNodeCache;
     /**
-     * @param composer CollectionComposer to be managed.
-     * @param mode TreeManager mode which is Relational or Independent.
+     * 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(composer: CollectionComposer<T>, mode?: TreeManagerMode);
+    constructor(input: T[] | CollectionComposer<T>, mode?: TreeManagerMode);
+    /**
+     * Returns all items as an array of `TreeNode`.
+     * @returns Array of `TreeNode` representing all items
+     */
+    getTreeNodes(): TreeNode<T>[];
+    /**
+     * 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: T): TreeNode<T> | null;
     /**
      * Is the manager maintaining parent/child relationships
      */
@@ -42,11 +60,11 @@ export declare class TreeManager<T extends TreeDataItem> {
      */
     private get items();
     /**
-     * Return all items which have children
+     * Returns all items with children
      */
     private get parentItems();
     /**
-     * Returns all checked items.
+     * Returns all selected items.
      * When managing relationships, this excludes groups/parents from the result.
      */
     get checkedItems(): readonly T[];
@@ -55,8 +73,8 @@ export declare class TreeManager<T extends TreeDataItem> {
      */
     protected get orderBySelectedAt(): (itemA: T, itemB: T) => number;
     /**
-     * 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(): readonly T[];
     /**
@@ -67,8 +85,8 @@ export declare class TreeManager<T extends TreeDataItem> {
      */
     private getEditableItems;
     /**
-     * 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(): readonly T[];
     /**
@@ -127,133 +145,138 @@ export declare class TreeManager<T extends TreeDataItem> {
      */
     private forceUpdateOnPath;
     /**
+     * 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}
      */
     setMode(mode: TreeManagerMode): void;
     /**
-     * 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: T): void;
     /**
-     * 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: T): boolean;
     /**
-     * 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: T): boolean;
     /**
-     * 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: T): boolean;
     /**
-     * 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: T): boolean;
     /**
-     * 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: T): boolean;
     /**
-     * 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: T): boolean;
     /**
-     * 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: T): CheckedState;
     /**
-     * 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: T): readonly T[];
     /**
-     * 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: T, depth?: number): readonly T[];
     /**
-     * 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: T): T | null;
     /**
-     * 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: T): readonly T[];
     /**
-     * Expand an item to show its children
+     * Expands the item to show its children.
      * @param item Original data item
      * @returns {void}
      */
     expandItem(item: T): void;
     /**
-     * Collapse an item to hide its children
+     * Collapses the item to hide its children.
      * @param item Original data item
      * @returns {void}
      */
     collapseItem(item: T): void;
     /**
-     * Expands all items in the tree
+     * Expands all items.
      * @returns {void}
      */
     expandAllItems(): void;
     /**
-     * Collapses all items in the tree
+     * Collapses all items.
      * @returns {void}
      */
     collapseAllItems(): void;
     /**
-     * Checks the item
+     * Selects the item.
      * @param item Original data item
      * @returns `True` if the item is modified
      */
     checkItem(item: T): boolean;
     private _checkItem;
     /**
-     * Unchecks the item
+     * Deselects the item.
      * @param item Original data item
      * @returns `True` if the item is modified
      */
     uncheckItem(item: T): boolean;
     private _uncheckItem;
     /**
-     * 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: T): boolean;
     /**
-     * Checks all items
+     * Selects all items.
      * @returns {void}
      */
     checkAllItems(): void;
     /**
-     * Unchecks all items
+     * Deselects all items.
      * @returns {void}
      */
     uncheckAllItems(): void;