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

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

@@ -0,0 +1,215 @@
+import { CheckedState } 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 class TreeNode {
+    /**
+     * 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, manager) {
+        this.item = item;
+        this.manager = manager;
+    }
+    /** Icon to show, when rendering the item. */
+    get icon() {
+        return this.getPropertyValue('icon');
+    }
+    set icon(icon) {
+        this.setProperty('icon', icon);
+    }
+    /** Label to show, when rendering the item. */
+    get label() {
+        return this.getPropertyValue('label');
+    }
+    set label(value) {
+        this.setProperty('label', value);
+    }
+    /**
+     * Value of the data item.
+     * This is usually the value which is returned,
+     * when the item is selected.
+     */
+    get value() {
+        return this.getPropertyValue('value');
+    }
+    set value(value) {
+        this.setProperty('value', value);
+    }
+    /**
+     * Sets the item to be readonly.
+     * Read only items cannot be selected by a user.
+     */
+    get readonly() {
+        return !!this.getPropertyValue('readonly');
+    }
+    set readonly(value) {
+        this.setProperty('readonly', value);
+    }
+    /**
+     * Sets the highlight state of the item.
+     * This is usually used for navigating over items,
+     * without affecting focus or multiple item selection.
+     */
+    get highlighted() {
+        return !!this.getPropertyValue('highlighted');
+    }
+    set highlighted(value) {
+        this.setProperty('highlighted', value);
+    }
+    /**
+     * Sets the item to be disabled.
+     * This completely prevents the item from being interacted with.
+     */
+    get disabled() {
+        return !!this.getPropertyValue('disabled');
+    }
+    set disabled(value) {
+        this.setProperty('disabled', value);
+    }
+    /**
+     * Whether to show or hide the item from the renderer.
+     * @readonly
+     */
+    // no setter due to a conflict with `hidden` usage in filterItems of Tree component.
+    get hidden() {
+        return !!this.getPropertyValue('hidden');
+    }
+    /** Expanded state of child items. If `true`, child items will be visible. */
+    get expanded() {
+        return this.manager.isItemExpanded(this.item);
+    }
+    set expanded(value) {
+        if (value) {
+            this.manager.expandItem(this.item);
+        }
+        else {
+            this.manager.collapseItem(this.item);
+        }
+    }
+    /**
+     * Timestamp indicating the order of sequential selection.
+     * @readonly
+     */
+    get selectedAt() {
+        return this.getPropertyValue('selectedAt');
+    }
+    /**
+     * 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() {
+        const checkedState = this.manager.getItemCheckedState(this.item);
+        return checkedState === CheckedState.CHECKED;
+    }
+    set selected(value) {
+        if (value) {
+            this.manager.checkItem(this.item);
+        }
+        else {
+            this.manager.uncheckItem(this.item);
+        }
+    }
+    /**
+     * 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() {
+        return this.manager.getItemCheckedState(this.item);
+    }
+    /**
+     * Returns all ancestors of the item.
+     * @returns An array of ancestors as Tree Node
+     */
+    getAncestors() {
+        const ancestors = this.manager.getItemAncestors(this.item);
+        return ancestors.map((ancestor) => this.manager.getTreeNode(ancestor));
+    }
+    /**
+     * Returns the children of the item.
+     * @returns An array of children as Tree Node
+     */
+    getChildren() {
+        const children = this.manager.getItemChildren(this.item);
+        return children.map((child) => this.manager.getTreeNode(child));
+    }
+    /**
+     * 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) {
+        const descendants = this.manager.getItemDescendants(this.item, depth);
+        return descendants.map((descendant) => this.manager.getTreeNode(descendant));
+    }
+    /**
+     * Returns the parent of the item, if it has one.
+     * @returns Item parent as Tree Node or `null`
+     */
+    getParent() {
+        const parent = this.manager.getItemParent(this.item);
+        return parent ? this.manager.getTreeNode(parent) : 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() {
+        return this.manager.isItemCheckable(this.item);
+    }
+    /**
+     * Returns whether the item contains any children or not.
+     * @returns `True` if the item has children
+     */
+    isParent() {
+        return this.manager.isItemParent(this.item);
+    }
+    /**
+     * Returns whether the item has a parent or not.
+     * @returns `True` if the item has a parent
+     */
+    isChild() {
+        return this.manager.isItemChild(this.item);
+    }
+    /**
+     * 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() {
+        return this.manager.composer.getItemDepth(this.item);
+    }
+    /**
+     * 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() {
+        this.manager.updateItem(this.item);
+    }
+    /**
+     * Retrieve a value of the specified property.
+     * @param prop property key
+     * @returns property value
+     */
+    getPropertyValue(prop) {
+        return this.manager.composer.getItemPropertyValue(this.item, prop);
+    }
+    /**
+     * Set a value of the specified property.
+     * @param prop property key
+     * @param value property value
+     * @returns {void}
+     */
+    setProperty(prop, value) {
+        return this.manager.composer.setItemPropertyValue(this.item, prop, value);
+    }
+}

package/lib/tree-select/custom-elements.json

@@ -43,6 +43,11 @@
           "type": "number",
           "default": "0"
         },
+        {
+          "name": "treeManager (readonly)",
+          "description": "Tree manager used for item manipulation",
+          "type": "TreeManager<TreeSelectDataItem>"
+        },
         {
           "name": "noRelation",
           "attribute": "no-relation",
@@ -117,6 +122,13 @@
           "name": "opened-changed",
           "description": "Fired when the user opens or closes control's popup. The event is not triggered if `opened` property is changed programmatically."
         }
+      ],
+      "methods": [
+        {
+          "name": "commit",
+          "description": "Commit the current selection applying it to `values` property.",
+          "params": []
+        }
       ]
     }
   ]

package/lib/tree-select/custom-elements.md

@@ -4,17 +4,24 @@ Dropdown control that allows selection from the tree list
 
 ## Properties
 
-| Property      | Attribute     | Type               | Default                                          | Description                                      |
-|---------------|---------------|--------------------|--------------------------------------------------|--------------------------------------------------|
-| `data`        |               | `TreeSelectData[]` | []                                               | Data object to be used for creating tree         |
-| `filterCount` |               | `number`           | 0                                                | Tracks the number of filter matches<br /><br />Only needed if internal filtering is unused |
-| `max`         | `max`         | `string \| null`   | ""                                               | Set maximum number of selected items             |
-| `noRelation`  | `no-relation` | `boolean`          | false                                            | Breaks the relationship when multiple<br />selection mode is enabled |
-| `opened`      | `opened`      | `boolean`          | false                                            | Set dropdown to open                             |
-| `placeholder` | `placeholder` | `string`           | ""                                               | Set placeholder text                             |
-| `renderer`    |               |                    | "createTreeSelectRenderer<TreeSelectDataItem>(this)" | Renderer used to render tree item elements       |
-| `showPills`   | `show-pills`  | `boolean`          | false                                            | Should the control show pills                    |
-| `values`      |               | `string[]`         | []                                               | Returns a values collection of the currently<br />selected item values |
+| Property                 | Attribute     | Type                              | Default                                          | Description                                      |
+|--------------------------|---------------|-----------------------------------|--------------------------------------------------|--------------------------------------------------|
+| `data`                   |               | `TreeSelectData[]`                | []                                               | Data object to be used for creating tree         |
+| `filterCount`            |               | `number`                          | 0                                                | Tracks the number of filter matches<br /><br />Only needed if internal filtering is unused |
+| `max`                    | `max`         | `string \| null`                  | ""                                               | Set maximum number of selected items             |
+| `noRelation`             | `no-relation` | `boolean`                         | false                                            | Breaks the relationship when multiple<br />selection mode is enabled |
+| `opened`                 | `opened`      | `boolean`                         | false                                            | Set dropdown to open                             |
+| `placeholder`            | `placeholder` | `string`                          | ""                                               | Set placeholder text                             |
+| `renderer`               |               |                                   | "createTreeSelectRenderer<TreeSelectDataItem>(this)" | Renderer used to render tree item elements       |
+| `showPills`              | `show-pills`  | `boolean`                         | false                                            | Should the control show pills                    |
+| `treeManager (readonly)` |               | `TreeManager<TreeSelectDataItem>` |                                                  | Tree manager used for item manipulation          |
+| `values`                 |               | `string[]`                        | []                                               | Returns a values collection of the currently<br />selected item values |
+
+## Methods
+
+| Method   | Type       | Description                                      |
+|----------|------------|--------------------------------------------------|
+| `commit` | `(): void` | Commit the current selection applying it to `values` property. |
 
 ## Events
 

package/lib/tree-select/index.d.ts

@@ -76,10 +76,11 @@ export declare class TreeSelect extends ComboBox<TreeSelectDataItem> {
      * Composer used for live changes
      */
     protected composer: CollectionComposer<TreeSelectDataItem>;
+    protected _treeManager: TreeManager<TreeSelectDataItem>;
     /**
-     * Provide access to tree interface
+     * Tree manager used for item manipulation
      */
-    protected treeManager: TreeManager<TreeSelectDataItem>;
+    get treeManager(): TreeManager<TreeSelectDataItem>;
     /**
      * Modification updates are called a lot
      *
@@ -112,7 +113,7 @@ export declare class TreeSelect extends ComboBox<TreeSelectDataItem> {
     /**
      * Renderer used to render tree item elements
      */
-    renderer: (item: import("../tree/index.js").TreeDataItem, composer: CollectionComposer<import("../tree/index.js").TreeDataItem>, element?: HTMLElement) => HTMLElement;
+    renderer: (item: import("../tree/index.js").TreeDataItem, composer: CollectionComposer<import("../tree/index.js").TreeDataItem>, element?: HTMLElement | undefined) => HTMLElement;
     private _max;
     /**
      * Set maximum number of selected items
@@ -202,12 +203,16 @@ export declare class TreeSelect extends ComboBox<TreeSelectDataItem> {
      */
     protected get isConfirmDisabled(): boolean;
     /**
-     * Persist the current selection
-     * Takes the current selection and uses it for {@link TreeSelect.values}
-     * Also uses current selection as a revert position for future changes
+     * Commit the current selection applying it to `values` property.
+     * @return {void}
+     */
+    commit(): void;
+    /**
+     * Persist the current selection applying it to @link TreeSelect.values}.
+     * @param shouldNotify Whether to notify the change with `value-changed` event or not.
      * @returns {void}
      */
-    protected persistSelection(): void;
+    private persistSelection;
     /**
      * Revert modified selection to old values. Run on Esc or Cancel
      * @returns {void}

package/lib/tree-select/index.js

@@ -82,10 +82,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
          * Composer used for live changes
          */
         this.composer = new CollectionComposer([]);
-        /**
-         * Provide access to tree interface
-         */
-        this.treeManager = new TreeManager(this.composer);
+        this._treeManager = new TreeManager(this.composer);
         /**
          * Modification updates are called a lot
          *
@@ -158,6 +155,12 @@ let TreeSelect = class TreeSelect extends ComboBox {
       }
     `;
     }
+    /**
+     * Tree manager used for item manipulation
+     */
+    get treeManager() {
+        return this._treeManager;
+    }
     /**
      * Returns a values collection of the currently
      * selected item values
@@ -217,7 +220,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
         const oldValue = this.resolvedData;
         if (value !== oldValue) {
             super.resolvedData = value;
-            this.treeManager = new TreeManager(this.composer, this.mode);
+            this._treeManager = new TreeManager(this.composer, this.mode);
             // keep the original values
             // do not use values setter to avoid unnecessary calls
             this._values = this.composerValues;
@@ -235,13 +238,13 @@ let TreeSelect = class TreeSelect extends ComboBox {
      * @override
      */
     get composerValues() {
-        return this.treeManager.checkedItems.map((item) => item.value || '').slice();
+        return this._treeManager.checkedItems.map((item) => item.value ?? '').slice();
     }
     /**
      * Provide list of currently selected items
      */
     get selection() {
-        return this.treeManager.checkedItems.slice();
+        return this._treeManager.checkedItems.slice();
     }
     /**
      * Get a list of selected item labels
@@ -307,7 +310,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
      * If mode is INDEPENDENT, grouping is not applied
      */
     get checkedGroupedItems() {
-        const treeManager = this.treeManager;
+        const treeManager = this._treeManager;
         const checkedItems = treeManager.checkedItems;
         if (this.mode === TreeManagerMode.INDEPENDENT) {
             return checkedItems;
@@ -347,18 +350,24 @@ let TreeSelect = class TreeSelect extends ComboBox {
         return Boolean(this.treeEl && this.max && this.treeEl.values.length > Number(this.max));
     }
     /**
-     * Persist the current selection
-     * Takes the current selection and uses it for {@link TreeSelect.values}
-     * Also uses current selection as a revert position for future changes
+     * Commit the current selection applying it to `values` property.
+     * @return {void}
+     */
+    commit() {
+        this.persistSelection();
+    }
+    /**
+     * Persist the current selection applying it to @link TreeSelect.values}.
+     * @param shouldNotify Whether to notify the change with `value-changed` event or not.
      * @returns {void}
      */
-    persistSelection() {
+    persistSelection(shouldNotify = false) {
         const oldValues = this.values;
         const newValues = this.composerValues;
         if (oldValues.toString() !== newValues.toString()) {
             // Set new values order by sequential selection
             this.values = newValues;
-            this.notifyPropertyChange('value', this.value);
+            shouldNotify && this.notifyPropertyChange('value', this.value);
         }
     }
     /**
@@ -402,7 +411,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
             const hasChildren = composer.getItemChildren(item).length;
             if (hasChildren) {
                 this.memo.expandable += 1;
-                if (this.treeManager.isItemExpanded(item) && this.treeManager.isItemCheckable(item)) {
+                if (this._treeManager.isItemExpanded(item) && this._treeManager.isItemCheckable(item)) {
                     this.memo.expanded += 1;
                 }
             }
@@ -436,7 +445,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
         const event = new CustomEvent('confirm');
         this.dispatchEvent(event);
         if (!event.defaultPrevented) {
-            this.persistSelection();
+            this.persistSelection(true);
             this.closeAndReset();
         }
     }
@@ -459,10 +468,10 @@ let TreeSelect = class TreeSelect extends ComboBox {
      */
     expansionToggleClickHandler() {
         if (this.hasExpansion) {
-            this.treeManager.collapseAllItems();
+            this._treeManager.collapseAllItems();
         }
         else {
-            this.treeManager.expandAllItems();
+            this._treeManager.expandAllItems();
         }
     }
     /**
@@ -472,10 +481,10 @@ let TreeSelect = class TreeSelect extends ComboBox {
      */
     selectionToggleHandler(event) {
         if (event.detail.value) {
-            this.treeManager.checkAllItems();
+            this._treeManager.checkAllItems();
         }
         else {
-            this.treeManager.uncheckAllItems();
+            this._treeManager.uncheckAllItems();
         }
     }
     /**
@@ -499,7 +508,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
      * @returns {void}
      */
     enterEditSelection() {
-        this.editSelectionItems = new Set(this.treeManager.checkedItems);
+        this.editSelectionItems = new Set(this._treeManager.checkedItems);
         this.filterItems();
     }
     /**
@@ -560,13 +569,13 @@ let TreeSelect = class TreeSelect extends ComboBox {
                 }
                 // item matches selection, can have conventional filter applied
                 if (result) {
-                    result = filter(item);
+                    result = filter(item, this._treeManager);
                 }
                 if (result) {
-                    this.treeManager.includeItem(item);
+                    this._treeManager.includeItem(item);
                 }
                 else {
-                    this.treeManager.excludeItem(item);
+                    this._treeManager.excludeItem(item);
                 }
                 return result;
             }).slice();
@@ -598,14 +607,14 @@ let TreeSelect = class TreeSelect extends ComboBox {
             /**
              * Collapse an item to prevent tree show too many nested expanded
              */
-            if (this.treeManager.isItemExpanded(item)) {
-                this.treeManager.collapseItem(item);
+            if (this._treeManager.isItemExpanded(item)) {
+                this._treeManager.collapseItem(item);
             }
             /**
              * show all descendants of items to make them all are selectable
              * and user can navigate into nested data
              */
-            const children = this.treeManager.getItemChildren(item);
+            const children = this._treeManager.getItemChildren(item);
             if (children.length) {
                 this.addNestedItemsToRender(children, items);
             }
@@ -623,8 +632,8 @@ let TreeSelect = class TreeSelect extends ComboBox {
             // Skip hidden and exclude item
             if (!item.hidden && !excludeItems.includes(item)) {
                 // Add item and nested children
-                this.treeManager.includeItem(item);
-                const children = this.treeManager.getItemChildren(item);
+                this._treeManager.includeItem(item);
+                const children = this._treeManager.getItemChildren(item);
                 if (children.length) {
                     this.addNestedItemsToRender(children, excludeItems);
                 }
@@ -643,9 +652,9 @@ let TreeSelect = class TreeSelect extends ComboBox {
         // we iterate each item match so as to find ancestors
         items.forEach((item) => {
             // get the ancestors
-            const parent = this.treeManager.getItemParent(item);
+            const parent = this._treeManager.getItemParent(item);
             if (parent && !ancestors.has(parent)) {
-                this.treeManager.getItemAncestors(item).forEach((ancestor) => {
+                this._treeManager.getItemAncestors(item).forEach((ancestor) => {
                     ancestors.add(ancestor); // track ancestors
                     this.addExpandedAncestorToRender(ancestor);
                 });
@@ -659,8 +668,8 @@ let TreeSelect = class TreeSelect extends ComboBox {
      * @returns {void}
      */
     addExpandedAncestorToRender(ancestor) {
-        this.treeManager.includeItem(ancestor);
-        this.treeManager.expandItem(ancestor);
+        this._treeManager.includeItem(ancestor);
+        this._treeManager.expandItem(ancestor);
     }
     /**
      * Reacts to pill removal by de-selecting the related item
@@ -672,7 +681,7 @@ let TreeSelect = class TreeSelect extends ComboBox {
         const pill = event.target;
         const item = this.queryItemsByPropertyValue('value', pill.value)[0];
         if (item) {
-            this.treeManager.uncheckItem(item);
+            this._treeManager.uncheckItem(item);
             // Focus must be shifted as otherwise focus is shifted to body once the item is removed and popup gets closed
             this.shiftFocus();
         }

package/lib/version.js

@@ -1 +1 @@
-export const VERSION = '7.10.10-next.1';
+export const VERSION = '7.11.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refinitiv-ui/elements",
-  "version": "7.10.10-next.1",
+  "version": "7.11.0",
   "description": "Element Framework Elements",
   "author": "LSEG",
   "license": "Apache-2.0",
@@ -353,25 +353,25 @@
     "tslib": "^2.3.1"
   },
   "devDependencies": {
-    "@refinitiv-ui/core": "^7.4.2-next.1",
-    "@refinitiv-ui/demo-block": "^7.1.9-next.1",
-    "@refinitiv-ui/i18n": "^7.1.4-next.0",
+    "@refinitiv-ui/core": "^7.4.3",
+    "@refinitiv-ui/demo-block": "^7.1.10",
+    "@refinitiv-ui/i18n": "^7.1.4",
     "@refinitiv-ui/phrasebook": "^7.1.1",
-    "@refinitiv-ui/test-helpers": "^7.1.1-next.0",
-    "@refinitiv-ui/translate": "^7.1.6-next.1",
-    "@refinitiv-ui/utils": "^7.2.0",
+    "@refinitiv-ui/test-helpers": "^7.1.1",
+    "@refinitiv-ui/translate": "^7.1.7",
+    "@refinitiv-ui/utils": "^7.3.0",
     "@types/d3-interpolate": "^3.0.1"
   },
   "peerDependencies": {
     "@refinitiv-ui/browser-sparkline": "^1.0.0 || ^2.0.0",
-    "@refinitiv-ui/core": "^7.4.2-next.1",
-    "@refinitiv-ui/i18n": "^7.1.4-next.0",
+    "@refinitiv-ui/core": "^7.4.3",
+    "@refinitiv-ui/i18n": "^7.1.4",
     "@refinitiv-ui/phrasebook": "^7.1.1",
-    "@refinitiv-ui/translate": "^7.1.6-next.1",
-    "@refinitiv-ui/utils": "^7.2.0"
+    "@refinitiv-ui/translate": "^7.1.7",
+    "@refinitiv-ui/utils": "^7.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3e4140dcb4943b98d30b78003e0cdb25cce86f68"
+  "gitHead": "b689d22c6cc53274a12b42233d087f9d5ccdee2e"
 }