@refinitiv-ui/elements 5.12.0-alpha.0 → 5.12.0

package/lib/list/index.js

@@ -0,0 +1,640 @@
+import { __decorate } from "tslib";
+import { ControlElement, css, html, WarningNotice } 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 { CollectionComposer } from '@refinitiv-ui/utils/lib/collection.js';
+import { ListRenderer } from './helpers/list-renderer.js';
+import '../item/index.js';
+export { ListRenderer };
+/**
+ * Key direction
+ */
+var Direction;
+(function (Direction) {
+    Direction[Direction["UP"] = -1] = "UP";
+    Direction[Direction["DOWN"] = 1] = "DOWN";
+})(Direction || (Direction = {}));
+const valueFormatWarning = new WarningNotice('The specified \'values\' format does not conform to the required format.');
+/**
+ * Provides listing and immutable selection
+ * @fires value-changed - Dispatched when value changes
+ */
+let List = class List extends ControlElement {
+    constructor() {
+        super(...arguments);
+        this.defaultRole = 'listbox';
+        /**
+         * Used to timestamp renders.
+         * This enables diff checking against item updates,
+         * rendering only items which have updated since the last render cycle.
+         */
+        this.renderTimestamp = new Map();
+        /**
+         * Requests an update after a composer modification.
+         * @returns Update promise.
+         */
+        this.modificationUpdate = () => {
+            this.requestUpdate();
+        };
+        /**
+         * Item map; used to link element nodes to data items.
+         */
+        this.itemMap = new Map();
+        /**
+         * Element map; used to link data items to element nodes.
+         */
+        this.elementMap = new Map();
+        /**
+         * Composer used to query and modify item state.
+         */
+        this.composer = new CollectionComposer([]);
+        /**
+         * Use default `tabindex` so that items are priority focus targets
+         */
+        this.defaultTabIndex = null;
+        /**
+         * Element focus delegation.
+         * Set to `false` and relies on native focusing.
+         */
+        this.delegatesFocus = false;
+        /**
+         * Renderer used to render list item elements
+         * @type {ListRenderer}
+         */
+        this.renderer = new ListRenderer(this);
+        /**
+         * Disable selections
+         */
+        this.stateless = false;
+        /**
+         * Aria indicating that list supports multiple selection
+         */
+        this.ariaMultiselectable = 'false';
+        /**
+         * Allow multiple selections
+         */
+        this.multiple = false;
+        this._data = null;
+    }
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version() {
+        return VERSION;
+    }
+    /**
+     * The data object, used to render the list.
+     * @type {ListData}
+     * @default null
+     */
+    get data() {
+        return this._data;
+    }
+    set data(value) {
+        const oldValue = this._data;
+        if (oldValue === value) {
+            return;
+        }
+        if (value instanceof CollectionComposer) {
+            this.composer = value;
+        }
+        else if (Array.isArray(value)) {
+            this.composer = new CollectionComposer(value);
+        }
+        else {
+            this.composer = new CollectionComposer([]);
+        }
+        this.composer.on('modification', // Listen for modifications
+        this.modificationUpdate // Update the template
+        );
+        this.clearMaps();
+        this._data = value;
+        this.requestUpdate('data', oldValue);
+    }
+    /**
+     * Returns the first selected item value.
+     * Use `values` when multiple selection mode is enabled.
+     * @default -
+     */
+    get value() {
+        return this.values[0] || '';
+    }
+    set value(value) {
+        const oldValue = this.value;
+        if (value !== oldValue || this.values.length > 1) {
+            this.clearSelection();
+            const item = this.queryItemsByPropertyValue('value', value)[0];
+            if (item) {
+                this.composer.setItemPropertyValue(item, 'selected', true);
+            }
+            this.requestUpdate('value', oldValue);
+        }
+    }
+    /**
+     * Returns a values collection of the currently
+     * selected item values
+     * @type {string[]}
+     * @default []
+     * @readonly
+     */
+    get values() {
+        return this.queryItemsByPropertyValue('selected', true)
+            .map((item) => this.composer.getItemPropertyValue(item, 'value'));
+    }
+    set values(values) {
+        if (!Array.isArray(values)) {
+            valueFormatWarning.show();
+            this.values = [];
+        }
+        else {
+            // Clone value arrays
+            const newValue = values.slice();
+            const oldValue = this.values.slice();
+            // Create comparison strings to check for differences
+            const newComparison = newValue.sort().toString();
+            const oldComparison = oldValue.sort().toString();
+            // Should we update the selection state?
+            if (newComparison !== oldComparison) {
+                this.clearSelection();
+                values.some((value) => {
+                    const matches = this.queryItemsByPropertyValue('value', value);
+                    matches.forEach((match) => this.composer.setItemPropertyValue(match, 'selected', true));
+                    return !this.multiple; // Only set the fist value if multiple is not enabled
+                });
+                this.requestUpdate('values', oldValue);
+            }
+        }
+    }
+    /**
+     * Selects an item in the list
+     * @param item Data Item or Item Element
+     * @returns If a selection has been made or not
+     */
+    selectItem(item) {
+        if (!this.stateless) {
+            if (item instanceof HTMLElement) {
+                item = this.itemFromElement(item);
+            }
+            if (item && this.multiple) {
+                const value = this.composer.getItemPropertyValue(item, 'selected');
+                this.composer.setItemPropertyValue(item, 'selected', !value);
+                return true;
+            }
+            if (item && this.composer.getItemPropertyValue(item, 'selected') !== true) {
+                this.clearSelection();
+                this.composer.setItemPropertyValue(item, 'selected', true);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Navigate up through the list items
+     * @returns {void}
+     */
+    up() {
+        this.highlightItem(this.getNextHighlightItem(Direction.UP), true);
+    }
+    /**
+     * Navigate down through the list items
+     * @returns {void}
+     */
+    down() {
+        this.highlightItem(this.getNextHighlightItem(Direction.DOWN), true);
+    }
+    /**
+     * Navigate to first focusable item of the list
+     * @returns {void}
+     */
+    first() {
+        const firstItem = this.itemMap.get(this.tabbableElements[0]);
+        this.highlightItem(firstItem, true);
+    }
+    /**
+     * Navigate to first focusable item of the list
+     * @returns {void}
+     */
+    last() {
+        const lastItem = this.itemMap.get(this.tabbableElements[this.tabbableElements.length - 1]);
+        this.highlightItem(lastItem, true);
+    }
+    /**
+     * Proxy for querying the composer
+     * @param engine composer querying engine
+     * @returns Collection of queried items
+     */
+    queryItems(engine) {
+        return this.composer.queryItems(engine);
+    }
+    /**
+     * Proxy for querying the composer by property and value
+     * @param property Property name
+     * @param value Property value
+     * @returns Collection of queried items
+     */
+    queryItemsByPropertyValue(property, value) {
+        return this.composer.queryItemsByPropertyValue(property, value);
+    }
+    /**
+     * Gets the associated element for the data item provided,
+     * if there is one available.
+     * @param item Item to map element to
+     * @returns Associated element
+     */
+    elementFromItem(item) {
+        return this.elementMap.get(item);
+    }
+    /**
+     * Gets the associated data item for the provided element,
+     * if there is one available.
+     * @param element Element to map item to
+     * @returns Associated date item
+     */
+    itemFromElement(element) {
+        return this.itemMap.get(element);
+    }
+    /**
+     * Tries to find the next focusable element.
+     * @param direction Direction to search
+     * @param element Starting element
+     * @returns Next logical element to focus
+     */
+    getNextFocusableItem(direction, element = this.activeElement) {
+        if (!element) {
+            return;
+        }
+        const children = this.tabbableItems;
+        if (children.length > 1) {
+            let index = children.indexOf(element) + direction;
+            index = index < 0 ? children.length - 1 : index === children.length ? 0 : index;
+            return children[index];
+        }
+    }
+    /**
+     * Tries to find the next highlight item
+     * @param direction Direction to search
+     * @returns A data item, if found.
+     */
+    getNextHighlightItem(direction) {
+        const highlightItem = this.queryItemsByPropertyValue('highlighted', true)[0];
+        const nextElement = this.getNextFocusableItem(direction) || this.getNextFocusableItem(direction, this.elementFromItem(highlightItem));
+        const backupElement = this.tabbableItems[0];
+        return nextElement ? this.itemFromElement(nextElement) : backupElement ? this.itemFromElement(backupElement) : undefined;
+    }
+    /**
+     * Clears any highlighted item
+     * @returns {void}
+     */
+    clearHighlighted() {
+        this.queryItemsByPropertyValue('highlighted', true)
+            .forEach(item => this.composer.setItemPropertyValue(item, 'highlighted', false));
+    }
+    /**
+     * Highlights a single item.
+     * Used for navigation.
+     * @param item Item to highlight
+     * @param scrollToItem Scroll the item into view?
+     * @returns {void}
+     */
+    highlightItem(item, scrollToItem = false) {
+        if (item) {
+            const elementToFocus = this.elementFromItem(item);
+            const focus = this.activeElement && this.activeElement !== elementToFocus;
+            this.clearHighlighted();
+            this.composer.setItemPropertyValue(item, 'highlighted', true);
+            focus && (elementToFocus === null || elementToFocus === void 0 ? void 0 : elementToFocus.focus({ preventScroll: true }));
+            scrollToItem && this.scrollToItem(item);
+        }
+    }
+    /**
+     * Gets the available tabbable elements
+     */
+    get tabbableItems() {
+        return Array.from(this.children)
+            .filter((el) => el.tabIndex >= 0);
+    }
+    /**
+     * Returns the current focused element
+     */
+    get activeElement() {
+        const el = this.getRootNode().activeElement;
+        const itemEl = this.findItemElementFromTarget(el);
+        if (itemEl && this.tabbableItems.includes(itemEl)) {
+            return itemEl;
+        }
+        return null;
+    }
+    /**
+     * Returns the current focused element
+     */
+    get highlightElement() {
+        const item = this.queryItemsByPropertyValue('highlighted', true)[0];
+        return item ? this.elementFromItem(item) || null : null;
+    }
+    /**
+     * Tries to select the current highlighted element
+     * @returns {void}
+     */
+    triggerActiveItem() {
+        const el = this.activeElement || this.highlightElement;
+        const item = el && this.itemFromElement(el);
+        item && this.selectItem(item) && this.fireSelectionUpdate();
+    }
+    /**
+     * Scroll to list item element
+     * @param item Data item to scroll to
+     * @returns {void}
+     */
+    scrollToItem(item) {
+        const element = this.elementFromItem(item);
+        if (element) {
+            const min = this.scrollTop;
+            const max = this.scrollTop + this.clientHeight - element.offsetHeight;
+            const pos = element.offsetTop;
+            pos > max ? this.scrollTop = element.offsetTop - this.clientHeight + element.offsetHeight
+                : pos < min ? this.scrollTop = element.offsetTop : 0;
+        }
+    }
+    /**
+     * Handles key input
+     * @param event Key down event object
+     * @returns {void}
+     */
+    onKeyDown(event) {
+        switch (event.key) {
+            case ' ':
+            case 'Spacebar':
+            case 'Enter':
+                this.triggerActiveItem();
+                break;
+            case 'Up':
+            case 'ArrowUp':
+                this.up();
+                break;
+            case 'Down':
+            case 'ArrowDown':
+                this.down();
+                break;
+            case 'Home':
+                this.first();
+                break;
+            case 'End':
+                this.last();
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+    }
+    /**
+     * Handle list on tap
+     * Typically it will select an item
+     * @param event Event to handle
+     * @returns {void}
+     */
+    onTap(event) {
+        const el = this.findItemElementFromTarget(event.target);
+        const item = el && this.itemFromElement(el);
+        if (item) {
+            this.clearHighlighted();
+            if (this.selectItem(item)) {
+                this.highlightItem(item);
+                this.fireSelectionUpdate();
+            }
+        }
+    }
+    /**
+     * Handles mouse move
+     * Typically it will highlight an item
+     * @param event Event to handle
+     * @returns {void}
+     */
+    onMouse(event) {
+        const el = this.findItemElementFromTarget(event.target);
+        const item = el ? this.itemFromElement(el) : null;
+        if (item && el !== this.highlightElement) {
+            if (this.activeElement) {
+                // prevent shifting focus to other items
+                // on mouse move and just fallback to host
+                this.activeElement.focus({ preventScroll: true });
+            }
+            this.highlightItem(item);
+        }
+    }
+    /**
+     * Handles item focus in
+     * Typically it will highlight the item
+     * @param event Event to handle
+     * @returns {void}
+     */
+    onFocus(event) {
+        const el = this.findItemElementFromTarget(event.target);
+        const item = el && this.itemFromElement(el);
+        if (item) {
+            this.highlightItem(item);
+        }
+    }
+    /**
+     * Handles item focus out
+     * Typically it will remove highlighting
+     * @returns {void}
+     */
+    onBlur() {
+        this.clearHighlighted();
+    }
+    /**
+     * Tries to find a known item element,
+     * from an event target
+     * @param target Event target
+     * @returns Found element, if available
+     */
+    findItemElementFromTarget(target) {
+        let el = target;
+        while (el) {
+            if (this.itemMap.has(el)) {
+                break; // known rendered item
+            }
+            el = el.parentElement;
+        }
+        return el;
+    }
+    /**
+     * Clears the current selected items
+     * @returns {void}
+     */
+    clearSelection() {
+        this.queryItemsByPropertyValue('selected', true)
+            .forEach((item) => this.composer.setItemPropertyValue(item, 'selected', false));
+        this.requestUpdate();
+    }
+    /**
+     * Queries and returns all renderable items.
+     * @returns Collection of renderable items
+     */
+    get renderItems() {
+        return this.queryItems((item, composer) => {
+            return composer.getItemPropertyValue(item, 'hidden') !== true;
+        });
+    }
+    /**
+     * Proxy for creating list item elements.
+     * Allows for a mapping to be created between
+     * Data Item and Item Element.
+     * @param item Data item context
+     * @param recyclableElements Child elements available for reuse
+     * @returns List item element
+     */
+    createListItem(item, recyclableElements) {
+        const cachedElement = this.elementFromItem(item);
+        const previousTimestamp = this.renderTimestamp.get(item) || NaN;
+        if (cachedElement && previousTimestamp > this.composer.getItemTimestamp(item)) {
+            return cachedElement; // don't re-render if the item hasn't changed
+        }
+        if (!cachedElement && recyclableElements.length) {
+            // Remove any old ties with the reusable element.
+            const recycledElement = recyclableElements.pop();
+            const previousItem = this.itemFromElement(recycledElement);
+            this.itemMap.delete(recycledElement);
+            previousItem && this.elementMap.delete(previousItem);
+            this.elementMap.set(item, recycledElement);
+        }
+        const freshElement = this.renderer(item, this.composer, this.elementFromItem(item));
+        if (cachedElement && cachedElement !== freshElement) {
+            // Renderer returned a new element, so remove the old link.
+            this.itemMap.delete(cachedElement);
+        }
+        this.itemMap.set(freshElement, item); // Link element to item
+        this.elementMap.set(item, freshElement); // Link item to element
+        this.renderTimestamp.set(item, performance.now());
+        return freshElement;
+    }
+    /**
+     * Clears all item-element and timestamp maps
+     * @returns {void}
+     */
+    clearMaps() {
+        this.itemMap.clear();
+        this.elementMap.clear();
+        this.renderTimestamp.clear();
+    }
+    /**
+     * Fire value changed event
+     * @returns {void}
+     */
+    fireSelectionUpdate() {
+        /**
+         * @event List#value-changed
+         */
+        this.notifyPropertyChange('value', this.value);
+    }
+    /**
+     * Calculates what elements can be recycled safely
+     * @param renderItems Current items to render
+     * @returns Collection of elements to be recycled
+     */
+    calculateRecyclableElements(renderItems) {
+        const result = [];
+        for (const element of this.children) {
+            const item = this.itemFromElement(element);
+            if (item && !renderItems.includes(item)) {
+                result.push(element);
+            }
+        }
+        return result;
+    }
+    /**
+     * Renders updates to light DOM
+     * @returns {void}
+     */
+    renderLightDOM() {
+        const renderItems = this.renderItems;
+        const currentChildren = Array.from(this.children);
+        const recyclableElements = this.calculateRecyclableElements(renderItems);
+        const renderChildren = renderItems.map((item) => this.createListItem(item, recyclableElements));
+        const deletions = currentChildren.filter(element => !renderChildren.includes(element));
+        deletions.forEach(element => this.removeChild(element));
+        renderChildren.forEach((element, index) => {
+            if (this.children.length === index) {
+                this.appendChild(element);
+            }
+            else if (element !== this.children[index]) {
+                this.insertBefore(element, this.children[index]);
+            }
+        });
+    }
+    firstUpdated(changeProperties) {
+        super.firstUpdated(changeProperties);
+        this.addEventListener('keydown', this.onKeyDown);
+        this.addEventListener('tap', this.onTap);
+        this.addEventListener('mousemove', this.onMouse);
+        this.addEventListener('mouseleave', this.clearHighlighted);
+        this.addEventListener('focusin', this.onFocus);
+        this.addEventListener('focusout', this.onBlur);
+    }
+    update(changeProperties) {
+        if (changeProperties.has('multiple')) {
+            this.renderTimestamp.clear(); // force render of all items
+        }
+        return super.update(changeProperties);
+    }
+    updated(changedProperties) {
+        super.updated(changedProperties);
+        if (changedProperties.has('multiple')) {
+            this.setAttribute('aria-multiselectable', this.multiple ? 'true' : 'false');
+        }
+    }
+    /**
+     * A `CSSResultGroup` that will be used
+     * to style the host, slotted children
+     * and the internal template of the element.
+     * @return CSS template
+     */
+    static get styles() {
+        return css `
+      :host {
+        display: block;
+        max-height: 600px;
+        overflow-y: auto;
+        position: relative; /* required for scrollToItem */
+      }
+    `;
+    }
+    /**
+     * A `TemplateResult` that will be used
+     * to render the updated internal template.
+     * @return Render template
+     */
+    render() {
+        this.renderLightDOM();
+        return html `<slot></slot>`;
+    }
+};
+__decorate([
+    property({ type: Function, attribute: false })
+], List.prototype, "renderer", void 0);
+__decorate([
+    property({ type: Boolean })
+], List.prototype, "stateless", void 0);
+__decorate([
+    property({ type: String, reflect: true, attribute: 'aria-multiselectable' })
+], List.prototype, "ariaMultiselectable", void 0);
+__decorate([
+    property({ type: Boolean })
+], List.prototype, "multiple", void 0);
+__decorate([
+    property({ attribute: false })
+], List.prototype, "data", null);
+__decorate([
+    property({ type: String })
+], List.prototype, "value", null);
+__decorate([
+    property({ type: Array, attribute: false })
+], List.prototype, "values", null);
+List = __decorate([
+    customElement('ef-list', {
+        alias: 'coral-list'
+    })
+], List);
+export { List };

package/lib/list/renderer.d.ts

@@ -0,0 +1,36 @@
+import { ExtensibleFunction } from './extensible-function.js';
+import type { DataItem, CollectionComposer } from '@refinitiv-ui/utils/lib/collection.js';
+/**
+ * Render function interface
+ * TODO: Move this to @refinitiv-ui/utils
+ * ! Do not import this module !
+ */
+export interface RenderFunction {
+    /**
+       * Renders data items into elements
+       * @param item Data item context
+       * @param composer Composer context
+       * @param element Reusable element. This element tries to be the same as was used before.
+       * @returns List item element
+   */
+    (item: DataItem, composer: CollectionComposer, element?: HTMLElement): HTMLElement;
+}
+/**
+ * Render constructor interface
+ * TODO: Move this to @refinitiv-ui/utils
+ * ! Do not import this module !
+ */
+export interface RendererConstructor {
+    /**
+     * @param fn Render function to use as the instance
+     */
+    new (fn: RenderFunction): RenderFunction;
+}
+/**
+ * Renderer base class.
+ * Used for creating renderers to render data items.
+ * TODO: Move this to @refinitiv-ui/utils
+ * ! Do not import this module !
+ */
+export declare abstract class Renderer extends ExtensibleFunction {
+}

package/lib/list/renderer.js

@@ -0,0 +1,9 @@
+import { ExtensibleFunction } from './extensible-function.js';
+/**
+ * Renderer base class.
+ * Used for creating renderers to render data items.
+ * TODO: Move this to @refinitiv-ui/utils
+ * ! Do not import this module !
+ */
+export class Renderer extends ExtensibleFunction {
+}