@refinitiv-ui/elements 5.3.3 → 5.3.4

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

@@ -0,0 +1,156 @@
+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';
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Selected items in tree
+     * @override
+     * @type {string[]}
+     */
+    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,286 @@
+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';
+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);
+        /**
+         * 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;
+        /**
+         * 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);
+        }
+        super.update(changedProperties);
+    }
+    /**
+     * Selected items in tree
+     * @override
+     * @type {string[]}
+     */
+    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({ attribute: false })
+], Tree.prototype, "renderer", void 0);
+Tree = __decorate([
+    customElement('ef-tree')
+], Tree);
+export { Tree };

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

@@ -0,0 +1,5 @@
+import { Renderer } from '../../list/renderer';
+import '../elements/tree-item';
+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';
+import { Renderer } from '../../list/renderer';
+import '../elements/tree-item';
+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;
+        });
+    }
+}

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

@@ -0,0 +1,17 @@
+import { CollectionComposer, DataItem } from '@refinitiv-ui/utils';
+export declare type TreeData<T extends TreeDataItem = TreeDataItem> = T[] | CollectionComposer<T> | null;
+export interface TreeDataItem extends DataItem {
+    /**
+     * Icon to show, when rendering the item.
+     */
+    icon?: string;
+    /**
+     * Label to show, when rendering the item.
+     */
+    label?: string;
+    /**
+     * Expanded state of child items.
+     * If `true`, child items will be visible
+     */
+    expanded?: boolean;
+}

package/lib/tree/helpers/types.js

@@ -0,0 +1 @@
+export {};

package/lib/tree/index.d.ts

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

package/lib/tree/index.js

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