@refinitiv-ui/elements 0.0.0-build.1957399501.1

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

@@ -0,0 +1,203 @@
+import { JSXInterface } from '../../jsx';
+import { PropertyValues, TapEvent } from '@refinitiv-ui/core';
+import { CollectionComposer } from '@refinitiv-ui/utils/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
+ *
+ * @fires value-changed - Fired when the users changed selection item.
+ * @fires expanded-changed - Fired when an item's expanded state has changed.
+ *
+ * @attr {boolean} [stateless=false] - Disable selections
+ * @prop {boolean} [stateless=false] - Disable selections
+ *
+ */
+export declare class Tree<T extends TreeDataItem = TreeDataItem> extends List<T> {
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version(): string;
+    protected readonly defaultRole: string | null;
+    /**
+     * Tree manager used for manipulation
+     */
+    private manager;
+    /**
+     * Allows multiple items to be selected
+     */
+    multiple: boolean;
+    /**
+     * Breaks the relationship when multiple
+     * 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}
+     */
+    renderer: TreeRenderer;
+    /**
+     * Expands all groups
+     * @returns {void}
+     */
+    expandAll(): void;
+    /**
+     * Collapses all groups
+     * @returns {void}
+     */
+    collapseAll(): void;
+    /**
+     * Checks all editable items
+     * @returns {void}
+     */
+    checkAll(): void;
+    /**
+     * Unchecks all editable items
+     * @returns {void}
+     */
+    uncheckAll(): void;
+    /**
+     * @override
+     * @ignore
+     */
+    selectItem(item: T): boolean;
+    /**
+     * Dispatches an event, detailing which item has recently changed it's expanded state.
+     * @param item Data item of which the expanded property changed
+     * @returns {void}
+     */
+    protected dispatchExpandedChangedEvent(item: T): void;
+    /**
+     * Handles tap event when composed path contains
+     * an element with an `expand-toggle` attribute.
+     * @param event Tap event to try and handle
+     * @returns True or False depending if the event was handled
+     */
+    protected handleExpandCollapse(event: TapEvent): boolean;
+    /**
+     * @override
+     */
+    protected onTap(event: TapEvent): void;
+    /**
+     * @override
+     */
+    protected onKeyDown(event: KeyboardEvent): void;
+    /**
+     * Performs left arrow keyboard action,
+     * collapsing a group item if possible.
+     * @returns {void}
+     */
+    protected left(): void;
+    /**
+     * Performs right arrow keyboard action,
+     * expanding a group item if possible.
+     * @returns {void}
+     */
+    protected right(): void;
+    /**
+     * Toggles the expanded state of an item.
+     * Executed when a user taps on an item to expand/collapse the group.
+     * @param item Original data item
+     * @returns {void}
+     */
+    protected toggleExpandedState(item: T): void;
+    /**
+     * @override
+     */
+    protected queryItems(engine: (item: T, composer: CollectionComposer<T>) => boolean): readonly T[];
+    /**
+     * @override
+     */
+    protected queryItemsByPropertyValue<K extends keyof T>(property: K, value: T[K]): readonly 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[]);
+    /**
+     * Data object to be used for creating tree
+     * @override
+     * @type {TreeData<T>}
+     */
+    get data(): TreeData<T>;
+    set data(data: TreeData<T>);
+    /**
+     * @override
+     */
+    protected get renderItems(): readonly T[];
+    /**
+     * Mode to use in the tree manager
+     */
+    protected get mode(): TreeManagerMode;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ef-tree': Tree;
+  }
+
+  namespace JSX {
+    interface IntrinsicElements {
+      'ef-tree': Partial<Tree> | JSXInterface.HTMLAttributes<Tree>;
+    }
+  }
+}
+
+export {};

package/lib/tree/elements/tree.js

@@ -0,0 +1,414 @@
+import { __decorate } from "tslib";
+import { customElement } from '@refinitiv-ui/core/decorators/custom-element.js';
+import { property } from '@refinitiv-ui/core/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
+ * to be used for menus and group selections
+ *
+ * @fires value-changed - Fired when the users changed selection item.
+ * @fires expanded-changed - Fired when an item's expanded state has changed.
+ *
+ * @attr {boolean} [stateless=false] - Disable selections
+ * @prop {boolean} [stateless=false] - Disable selections
+ *
+ */
+let Tree = class Tree extends List {
+    constructor() {
+        super(...arguments);
+        this.defaultRole = 'tree';
+        /**
+         * Tree manager used for manipulation
+         */
+        this.manager = new TreeManager(this.composer);
+        /**
+         * Allows multiple items to be selected
+         */
+        this.multiple = false;
+        /**
+         * Breaks the relationship when multiple
+         * 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}
+         */
+        this.renderer = new TreeRenderer(this);
+    }
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version() {
+        return VERSION;
+    }
+    /**
+     * Expands all groups
+     * @returns {void}
+     */
+    expandAll() {
+        this.manager.expandAllItems();
+    }
+    /**
+     * Collapses all groups
+     * @returns {void}
+     */
+    collapseAll() {
+        this.manager.collapseAllItems();
+    }
+    /**
+     * Checks all editable items
+     * @returns {void}
+     */
+    checkAll() {
+        if (!this.multiple) {
+            throw new RangeError('You cannot check all items in single selection mode');
+        }
+        this.manager.checkAllItems();
+    }
+    /**
+     * Unchecks all editable items
+     * @returns {void}
+     */
+    uncheckAll() {
+        this.manager.uncheckAllItems();
+    }
+    /**
+     * @override
+     * @ignore
+     */
+    selectItem(item) {
+        // Stateless tree
+        if (this.stateless) {
+            return false;
+        }
+        // Multiple selection
+        if (this.multiple) {
+            return this.manager.toggleItem(item);
+        }
+        // Single selection - expand/collapse group (parent)
+        if (this.manager.isItemParent(item)) {
+            this.toggleExpandedState(item);
+            return false;
+        }
+        // Single selection - check item
+        if (this.manager.checkItem(item)) {
+            this.manager.checkedItems.forEach(checkedItem => {
+                checkedItem !== item && this.manager.uncheckItem(checkedItem);
+            });
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Dispatches an event, detailing which item has recently changed it's expanded state.
+     * @param item Data item of which the expanded property changed
+     * @returns {void}
+     */
+    dispatchExpandedChangedEvent(item) {
+        /**
+        * Property `detail.value` is the current expanded state.
+        * Property `detail.item` is the original data item of which the property has been modified.
+        */
+        const event = new CustomEvent('expanded-changed', {
+            bubbles: false,
+            cancelable: false,
+            composed: true,
+            detail: {
+                value: this.manager.isItemExpanded(item),
+                item
+            }
+        });
+        this.dispatchEvent(event);
+    }
+    /**
+     * Handles tap event when composed path contains
+     * an element with an `expand-toggle` attribute.
+     * @param event Tap event to try and handle
+     * @returns True or False depending if the event was handled
+     */
+    handleExpandCollapse(event) {
+        const containsToggle = event.composedPath().some((target) => target instanceof HTMLElement && target.hasAttribute(EXPAND_TOGGLE_ATTR));
+        const itemElement = containsToggle && this.findItemElementFromTarget(event.target);
+        const item = itemElement && this.itemFromElement(itemElement);
+        if (item) {
+            this.toggleExpandedState(item);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * @override
+     */
+    onTap(event) {
+        if (this.handleExpandCollapse(event)) {
+            return;
+        }
+        super.onTap(event);
+    }
+    /**
+     * @override
+     */
+    onKeyDown(event) {
+        switch (event.key) {
+            case 'Left':
+            case 'ArrowLeft':
+                this.left();
+                break;
+            case 'Right':
+            case 'ArrowRight':
+                this.right();
+                break;
+            default:
+                return super.onKeyDown(event);
+        }
+        event.preventDefault();
+    }
+    /**
+     * Performs left arrow keyboard action,
+     * collapsing a group item if possible.
+     * @returns {void}
+     */
+    left() {
+        const item = this.highlightElement && this.itemFromElement(this.highlightElement);
+        if (item && this.manager.isItemExpanded(item)) {
+            this.manager.collapseItem(item);
+            this.dispatchExpandedChangedEvent(item);
+        }
+    }
+    /**
+     * Performs right arrow keyboard action,
+     * expanding a group item if possible.
+     * @returns {void}
+     */
+    right() {
+        const item = this.highlightElement && this.itemFromElement(this.highlightElement);
+        if (item && !this.manager.isItemExpanded(item)) {
+            this.manager.expandItem(item);
+            this.dispatchExpandedChangedEvent(item);
+        }
+    }
+    /**
+     * Toggles the expanded state of an item.
+     * Executed when a user taps on an item to expand/collapse the group.
+     * @param item Original data item
+     * @returns {void}
+     */
+    toggleExpandedState(item) {
+        if (this.manager.isItemExpanded(item)) {
+            this.manager.collapseItem(item);
+        }
+        else {
+            this.manager.expandItem(item);
+        }
+        this.dispatchExpandedChangedEvent(item);
+    }
+    /**
+     * @override
+     */
+    queryItems(engine) {
+        return this.composer.queryItems(engine, Infinity);
+    }
+    /**
+     * @override
+     */
+    queryItemsByPropertyValue(property, value) {
+        return this.composer.queryItemsByPropertyValue(property, value, Infinity);
+    }
+    /**
+     * @override
+     */
+    update(changedProperties) {
+        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 => {
+            return this.composer.getItemPropertyValue(item, 'value') || '';
+        });
+    }
+    set values(value) {
+        super.values = value;
+    }
+    /**
+     * Data object to be used for creating tree
+     * @override
+     * @type {TreeData<T>}
+     */
+    get data() {
+        return super.data;
+    }
+    set data(data) {
+        super.data = data;
+        this.manager = new TreeManager(this.composer, this.mode);
+    }
+    /**
+     * @override
+     */
+    get renderItems() {
+        return this.manager.visibleItems;
+    }
+    /**
+     * Mode to use in the tree manager
+     */
+    get mode() {
+        return !this.multiple || !this.noRelation
+            ? TreeManagerMode.RELATIONAL : TreeManagerMode.INDEPENDENT;
+    }
+};
+__decorate([
+    property({ type: Boolean })
+], Tree.prototype, "multiple", void 0);
+__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);
+Tree = __decorate([
+    customElement('ef-tree')
+], Tree);
+export { Tree };

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,33 @@
+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;
+        let currentMode;
+        let currentComposer;
+        super((item, composer, element = document.createElement('ef-tree-item')) => {
+            const el = element;
+            const multiple = !!scope && scope.multiple === true;
+            const noRelation = !!scope && scope.noRelation === true;
+            const mode = !multiple || !noRelation ? TreeManagerMode.RELATIONAL : TreeManagerMode.INDEPENDENT;
+            if (currentComposer !== composer || currentMode !== mode) {
+                currentMode = mode;
+                currentComposer = composer;
+                manager = new TreeManager(composer, mode);
+            }
+            el.multiple = multiple;
+            el.item = item;
+            el.depth = composer.getItemDepth(item);
+            el.parent = composer.getItemChildren(item).length > 0;
+            el.expanded = manager.isItemExpanded(item);
+            el.checkedState = !multiple && el.parent ? CheckedState.UNCHECKED : manager.getItemCheckedState(item);
+            el.icon = composer.getItemPropertyValue(item, 'icon');
+            el.label = composer.getItemPropertyValue(item, 'label');
+            el.disabled = composer.getItemPropertyValue(item, 'disabled') === true;
+            el.readonly = composer.getItemPropertyValue(item, 'readonly') === true;
+            el.highlighted = composer.getItemPropertyValue(item, 'highlighted') === true;
+            return el;
+        });
+    }
+}