@refinitiv-ui/elements 5.3.3 → 5.7.0

package/lib/tree/custom-elements.json

@@ -0,0 +1,113 @@
+{
+  "version": "experimental",
+  "tags": [
+    {
+      "name": "ef-tree",
+      "description": "Displays a tree structure\nto be used for menus and group selections",
+      "attributes": [
+        {
+          "name": "multiple",
+          "description": "Allows multiple items to be selected",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "no-relation",
+          "description": "Breaks the relationship when multiple\nselection mode is enabled",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "query",
+          "description": "Query string applied to tree",
+          "type": "string",
+          "default": "\"\""
+        },
+        {
+          "name": "stateless",
+          "description": "Disable selections",
+          "type": "boolean",
+          "default": "false"
+        }
+      ],
+      "properties": [
+        {
+          "name": "multiple",
+          "attribute": "multiple",
+          "description": "Allows multiple items to be selected",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "noRelation",
+          "attribute": "no-relation",
+          "description": "Breaks the relationship when multiple\nselection mode is enabled",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "query",
+          "attribute": "query",
+          "description": "Query string applied to tree",
+          "type": "string",
+          "default": "\"\""
+        },
+        {
+          "name": "renderer",
+          "description": "Renderer used for generating tree items",
+          "type": "TreeRenderer",
+          "default": "\"new TreeRenderer(this)\""
+        },
+        {
+          "name": "values",
+          "description": "Selected items in tree",
+          "type": "string[]"
+        },
+        {
+          "name": "data",
+          "description": "Data object to be used for creating tree",
+          "type": "TreeData<T>"
+        },
+        {
+          "name": "stateless",
+          "attribute": "stateless",
+          "description": "Disable selections",
+          "type": "boolean",
+          "default": "false"
+        }
+      ],
+      "events": [
+        {
+          "name": "value-changed",
+          "description": "Fired when the users changed selection item."
+        },
+        {
+          "name": "expanded-changed",
+          "description": "Fired when an item's expanded state has changed."
+        }
+      ],
+      "methods": [
+        {
+          "name": "expandAll",
+          "description": "Expands all groups",
+          "params": []
+        },
+        {
+          "name": "collapseAll",
+          "description": "Collapses all groups",
+          "params": []
+        },
+        {
+          "name": "checkAll",
+          "description": "Checks all editable items",
+          "params": []
+        },
+        {
+          "name": "uncheckAll",
+          "description": "Unchecks all editable items",
+          "params": []
+        }
+      ]
+    }
+  ]
+}

package/lib/tree/custom-elements.md

@@ -0,0 +1,32 @@
+# ef-tree
+
+Displays a tree structure
+to be used for menus and group selections
+
+## Properties
+
+| Property     | Attribute     | Type           | Default                  | Description                                      |
+|--------------|---------------|----------------|--------------------------|--------------------------------------------------|
+| `data`       |               | `TreeData<T>`  |                          | Data object to be used for creating tree         |
+| `multiple`   | `multiple`    | `boolean`      | false                    | Allows multiple items to be selected             |
+| `noRelation` | `no-relation` | `boolean`      | false                    | Breaks the relationship when multiple<br />selection mode is enabled |
+| `query`      | `query`       | `string`       | ""                       | Query string applied to tree                     |
+| `renderer`   |               | `TreeRenderer` | "new TreeRenderer(this)" | Renderer used for generating tree items          |
+| `stateless`  | `stateless`   | `boolean`      | false                    | Disable selections                               |
+| `values`     |               | `string[]`     |                          | Selected items in tree                           |
+
+## Methods
+
+| Method        | Type       | Description                 |
+|---------------|------------|-----------------------------|
+| `checkAll`    | `(): void` | Checks all editable items   |
+| `collapseAll` | `(): void` | Collapses all groups        |
+| `expandAll`   | `(): void` | Expands all groups          |
+| `uncheckAll`  | `(): void` | Unchecks all editable items |
+
+## Events
+
+| Event              | Description                                      |
+|--------------------|--------------------------------------------------|
+| `expanded-changed` | Fired when an item's expanded state has changed. |
+| `value-changed`    | Fired when the users changed selection item.     |

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

@@ -0,0 +1,96 @@
+import { JSXInterface } from '../../jsx';
+import { TemplateResult, ControlElement, PropertyValues } from '@refinitiv-ui/core';
+import '../../icon/index.js';
+import '../../checkbox/index.js';
+import type { TreeDataItem } from '../helpers/types';
+import { CheckedState } from '../managers/tree-manager.js';
+/**
+ * Displays a tree list item.
+ * Groups display expansion arrows.
+ */
+export declare class TreeItem<T extends TreeDataItem = TreeDataItem> extends ControlElement {
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version(): string;
+    /**
+     * Checked state of the item
+     */
+    checkedState: CheckedState;
+    /**
+     * Is the item a parent and should it show an expansion toggle?
+     */
+    parent: boolean;
+    /**
+     * Display in multiple selection mode
+     */
+    multiple: boolean;
+    /**
+     * Expanded state of the item
+     */
+    expanded: boolean;
+    /**
+     * Depth of the item
+     */
+    depth: number;
+    /**
+     * Label of the item
+     */
+    label: string;
+    /**
+     * Icon of the item
+     */
+    icon: string;
+    /**
+     * Original data item, used for interacting with the tree manager
+     */
+    item: T;
+    /**
+     * Highlighted state of the item.
+     * This is for showing which item is currently being interacted with.
+     */
+    highlighted: boolean;
+    /**
+     * Template for rendering the indentation element
+     */
+    protected get indentTemplate(): TemplateResult;
+    /**
+     * Template for rendering the toggle
+     *
+     * ! expand-toggle is required for automatically toggling expanded state
+     */
+    protected get toggleTemplate(): TemplateResult;
+    /**
+     * Template for rendering the checkbox
+     */
+    protected get checkboxTemplate(): TemplateResult;
+    /**
+     * Template for rendering the icon
+     */
+    protected get iconTemplate(): TemplateResult;
+    /**
+     * Is the item fully checked?
+     */
+    protected get checked(): boolean;
+    /**
+     * Is the checked state indeterminate?
+     */
+    protected get indeterminate(): boolean;
+    protected update(changedProperties: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ef-tree-item': TreeItem;
+  }
+
+  namespace JSX {
+    interface IntrinsicElements {
+      'ef-tree-item': Partial<TreeItem> | JSXInterface.HTMLAttributes<TreeItem>;
+    }
+  }
+}
+
+export {};

package/lib/tree/elements/tree-item.js

@@ -0,0 +1,179 @@
+import { __decorate } from "tslib";
+import { html, ControlElement } from '@refinitiv-ui/core';
+import { customElement } from '@refinitiv-ui/core/lib/decorators/custom-element.js';
+import { property } from '@refinitiv-ui/core/lib/decorators/property.js';
+import { VERSION } from '../../version.js';
+import '../../icon/index.js';
+import { preload } from '../../icon/index.js';
+import '../../checkbox/index.js';
+import { CheckedState } from '../managers/tree-manager.js';
+preload('right');
+const emptyTemplate = html ``;
+/**
+ * Displays a tree list item.
+ * Groups display expansion arrows.
+ */
+let TreeItem = class TreeItem extends ControlElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Checked state of the item
+         */
+        this.checkedState = CheckedState.UNCHECKED;
+        /**
+         * Is the item a parent and should it show an expansion toggle?
+         */
+        this.parent = false;
+        /**
+         * Display in multiple selection mode
+         */
+        this.multiple = false;
+        /**
+         * Expanded state of the item
+         */
+        this.expanded = false;
+        /**
+         * Depth of the item
+         */
+        this.depth = 0;
+        /**
+         * Label of the item
+         */
+        this.label = '';
+        /**
+         * Icon of the item
+         */
+        this.icon = '';
+        /**
+         * Highlighted state of the item.
+         * This is for showing which item is currently being interacted with.
+         */
+        this.highlighted = false;
+    }
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version() {
+        return VERSION;
+    }
+    /**
+     * Template for rendering the indentation element
+     */
+    get indentTemplate() {
+        return this.depth ? html `<div part="indent" style="width:${this.depth}em"></div>` : emptyTemplate;
+    }
+    /**
+     * Template for rendering the toggle
+     *
+     * ! expand-toggle is required for automatically toggling expanded state
+     */
+    get toggleTemplate() {
+        return html `
+    <div
+    expand-toggle
+    part="toggle"
+    style="pointer-events:all;visibility:${this.parent ? 'visible' : 'hidden'}">
+      <ef-icon part="toggle-icon${this.expanded ? ' toggle-icon-expanded' : ''}" icon="right"></ef-icon>
+    </div>
+    `;
+    }
+    /**
+     * Template for rendering the checkbox
+     */
+    get checkboxTemplate() {
+        if (!this.multiple) {
+            return emptyTemplate;
+        }
+        return html `
+    <ef-checkbox
+    part="checkbox"
+    tabindex="-1"
+    .disabled="${this.disabled}"
+    .readonly="${this.readonly}"
+    .indeterminate="${this.indeterminate}"
+    .checked="${this.checked}"
+    style="pointer-events:none"></ef-checkbox>
+    `;
+    }
+    /**
+     * Template for rendering the icon
+     */
+    get iconTemplate() {
+        if (typeof this.icon === 'undefined') {
+            return emptyTemplate;
+        }
+        return html `<ef-icon part="label-icon" icon="${this.icon}"></ef-icon>`;
+    }
+    /**
+     * Is the item fully checked?
+     */
+    get checked() {
+        return this.checkedState === CheckedState.CHECKED;
+    }
+    /**
+     * Is the checked state indeterminate?
+     */
+    get indeterminate() {
+        return this.checkedState === CheckedState.INDETERMINATE;
+    }
+    update(changedProperties) {
+        super.update(changedProperties);
+        if (changedProperties.has('checkedState')) {
+            switch (this.checkedState) {
+                case CheckedState.CHECKED:
+                    this.setAttribute('selected', '');
+                    break;
+                case CheckedState.INDETERMINATE:
+                    this.setAttribute('selected', 'indeterminate');
+                    break;
+                default:
+                    this.removeAttribute('selected');
+            }
+        }
+    }
+    render() {
+        return html `
+      ${this.indentTemplate}
+      ${this.toggleTemplate}
+      ${this.checkboxTemplate}
+      ${this.iconTemplate}
+      <div part="label">
+        <slot>${this.label}</slot>
+      </div>
+  `;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], TreeItem.prototype, "checkedState", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'group' })
+], TreeItem.prototype, "parent", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], TreeItem.prototype, "multiple", void 0);
+__decorate([
+    property({ type: Boolean })
+], TreeItem.prototype, "expanded", void 0);
+__decorate([
+    property({ reflect: true, type: Number })
+], TreeItem.prototype, "depth", void 0);
+__decorate([
+    property({ type: String })
+], TreeItem.prototype, "label", void 0);
+__decorate([
+    property({ type: String })
+], TreeItem.prototype, "icon", void 0);
+__decorate([
+    property({ attribute: false })
+], TreeItem.prototype, "item", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], TreeItem.prototype, "highlighted", void 0);
+TreeItem = __decorate([
+    customElement('ef-tree-item', {
+        alias: 'coral-tree-item'
+    })
+], TreeItem);
+export { TreeItem };

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

@@ -0,0 +1,201 @@
+import { JSXInterface } from '../../jsx';
+import { PropertyValues, TapEvent } from '@refinitiv-ui/core';
+import { CollectionComposer } from '@refinitiv-ui/utils/lib/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;
+    /**
+     * 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[]}
+     */
+    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 {};