@refinitiv-ui/elements 5.3.3 → 5.3.4

package/lib/autosuggest/custom-elements.json

@@ -0,0 +1,223 @@
+{
+  "version": "experimental",
+  "tags": [
+    {
+      "name": "ef-autosuggest",
+      "description": "Shows suggestions based on users' query.\nIt can be used by attaching to text form control\nsuch as TextField, Multi Input, etc.\nAutosuggest supports various use cases such as\ncustom rendering, pagination, asynchronous data request, etc.",
+      "attributes": [
+        {
+          "name": "attach",
+          "description": "An HTML Element or CSS selector",
+          "type": "AutosuggestTargetElement | string | null"
+        },
+        {
+          "name": "request-on-focus",
+          "description": "Request suggestions when attach target is focused",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "more-results",
+          "description": "If set to true display 'Has more results' item",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "more-search-text",
+          "description": "Custom text for More Search",
+          "type": "string",
+          "default": "\"defaultMoreSearchText\""
+        },
+        {
+          "name": "loading",
+          "description": "If set to true show loading mask",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "debounce-rate",
+          "description": "Debounce rate in ms of the filter as a number.\nUsed to throttle the filter rate so as not to trigger unneeded filtering",
+          "type": "number",
+          "default": "\"100\""
+        },
+        {
+          "name": "html-renderer",
+          "description": "If set to true, the render function is not called. Instead the wrapper element\nshould populate and destroy suggestion elements. Rendering items manually\nmay have performance benefits in frameworks that use virtual DOM (such as `Vue`, `React`, `hyperHTML` and others)",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "opened",
+          "description": "Auto suggest popup's open state",
+          "type": "boolean",
+          "default": "\"false\""
+        }
+      ],
+      "properties": [
+        {
+          "name": "attach",
+          "attribute": "attach",
+          "description": "An HTML Element or CSS selector",
+          "type": "AutosuggestTargetElement | string | null"
+        },
+        {
+          "name": "requestOnFocus",
+          "attribute": "request-on-focus",
+          "description": "Request suggestions when attach target is focused",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "moreResults",
+          "attribute": "more-results",
+          "description": "If set to true display 'Has more results' item",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "moreSearchText",
+          "attribute": "more-search-text",
+          "description": "Custom text for More Search",
+          "type": "string",
+          "default": "\"defaultMoreSearchText\""
+        },
+        {
+          "name": "loading",
+          "attribute": "loading",
+          "description": "If set to true show loading mask",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "query",
+          "description": "An object that represents a query from attach target",
+          "type": "AutosuggestQuery | null"
+        },
+        {
+          "name": "debounceRate",
+          "attribute": "debounce-rate",
+          "description": "Debounce rate in ms of the filter as a number.\nUsed to throttle the filter rate so as not to trigger unneeded filtering",
+          "type": "number",
+          "default": "\"100\""
+        },
+        {
+          "name": "renderer",
+          "description": "A renderer applied to suggestion.\nBy default a render maps data to item attributes",
+          "type": "AutosuggestRenderer",
+          "default": "\"itemRenderer\""
+        },
+        {
+          "name": "highlightable",
+          "description": "A function that is applied to every suggestion during the render process\nto say whether the item can be highlighted and selected. Only items that return true are considered.\nBy default the function checks for `item` `highlightable` property.",
+          "type": "AutosuggestHighlightable",
+          "default": "\"itemHighlightable\""
+        },
+        {
+          "name": "suggestions",
+          "description": "A list of suggestion items",
+          "type": "AutosuggestItem[]",
+          "default": "[]"
+        },
+        {
+          "name": "htmlRenderer",
+          "attribute": "html-renderer",
+          "description": "If set to true, the render function is not called. Instead the wrapper element\nshould populate and destroy suggestion elements. Rendering items manually\nmay have performance benefits in frameworks that use virtual DOM (such as `Vue`, `React`, `hyperHTML` and others)",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "opened",
+          "attribute": "opened",
+          "description": "Auto suggest popup's open state",
+          "type": "boolean",
+          "default": "\"false\""
+        }
+      ],
+      "events": [
+        {
+          "name": "item-highlight",
+          "description": "Fired when an item gets highlighted or highlight is removed"
+        },
+        {
+          "name": "add-attach-target-events",
+          "description": "Fired when attach has been set"
+        },
+        {
+          "name": "remove-attach-target-events",
+          "description": "Fired when attach has been removed"
+        },
+        {
+          "name": "item-select",
+          "description": "Fired when an item gets selected"
+        },
+        {
+          "name": "suggestions-fetch-requested",
+          "description": "Fired when auto suggest requests the data"
+        },
+        {
+          "name": "suggestions-clear-requested",
+          "description": "Fired when auto suggest requests to clear the data. If used in reactive application, prevent default and set suggestions to []"
+        },
+        {
+          "name": "suggestions-query",
+          "description": "Fired when input value has changed and the query must be set"
+        },
+        {
+          "name": "suggestions-changed",
+          "description": "Fired when suggestions changed"
+        }
+      ],
+      "methods": [
+        {
+          "name": "onInputValueChange",
+          "description": "Run when attach target value changes.",
+          "params": [
+            {
+              "name": "event",
+              "description": "by default `value-changed` event is listened",
+              "type": "Event"
+            }
+          ]
+        },
+        {
+          "name": "onInputBlur",
+          "description": "Run when input has lost focus",
+          "params": [
+            {
+              "name": "event",
+              "description": "by default `blur` event is listened",
+              "type": "FocusEvent"
+            }
+          ]
+        },
+        {
+          "name": "onInputFocus",
+          "description": "Run when input received focus",
+          "params": [
+            {
+              "name": "event",
+              "description": "by default `focus` event is listened",
+              "type": "FocusEvent"
+            }
+          ]
+        },
+        {
+          "name": "onInputKeyDown",
+          "description": "Run when input key down event has happened",
+          "params": [
+            {
+              "name": "event",
+              "description": "by default `keydown` event is listened",
+              "type": "KeyboardEvent"
+            }
+          ]
+        },
+        {
+          "name": "refit",
+          "description": "Set the width",
+          "params": []
+        }
+      ]
+    }
+  ]
+}

package/lib/autosuggest/helpers/const.d.ts

@@ -0,0 +1,2 @@
+export declare const isIE: boolean;
+export declare const isMobile: boolean;

package/lib/autosuggest/helpers/const.js

@@ -0,0 +1,3 @@
+// TODO: use metrics once available
+export const isIE = (/Trident/g).test(navigator.userAgent);
+export const isMobile = (/iPhone|iPad|iPod|Android/i).test(window.navigator.userAgent);

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

@@ -0,0 +1,54 @@
+import { ItemType } from '../../item';
+export declare type AutosuggestSelectItemEvent = CustomEvent<{
+    query: string;
+    suggestion: Suggestion;
+}>;
+export declare type AutosuggestHighlightItem = {
+    highlighted: boolean;
+};
+export declare type AutosuggestHighlightItemEvent = CustomEvent<{
+    target: AutosuggestHighlightItem;
+    oldTarget: AutosuggestHighlightItem;
+}>;
+export declare type AutosuggestQueryAction = (event: CustomEvent) => void;
+export declare type AutosuggestReason = 'value-changed' | 'input-focus' | 'suggestions-revealed' | 'escape-pressed' | 'enter-pressed' | 'more-results';
+export interface Suggestion {
+    /**
+     * Type of item. Value can be `text`, `header`, `divider`
+     */
+    type?: ItemType;
+    /**
+     * The text for the label indicating the meaning of the item.
+     */
+    label?: string;
+    /**
+     * The text for the pop-up of item when it's hover.
+     */
+    title?: string;
+    /**
+     * Set the icon name from the coral-icon list
+     */
+    icon?: string;
+    /**
+     * Sets the item to be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Value of the data item.
+     */
+    value?: string;
+    /**
+     * Sort data item into the group.
+     */
+    group?: string;
+}
+export declare type AutosuggestItem = Suggestion | string | unknown;
+export interface AutosuggestQuery {
+    toString(): string;
+}
+export declare type AutosuggestTargetElement = HTMLElement & {
+    value: string;
+};
+export declare type AutosuggestMethodType = 'click' | 'enter' | 'clear' | 'reset' | 'navigation';
+export declare type AutosuggestRenderer = (suggestion: AutosuggestItem, query: AutosuggestQuery | null) => HTMLElement;
+export declare type AutosuggestHighlightable = (suggestion: AutosuggestItem, target: HTMLElement) => boolean;

package/lib/autosuggest/helpers/types.js

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

package/lib/autosuggest/helpers/utils.d.ts

@@ -0,0 +1,39 @@
+import { Item } from '../../item';
+import { AutosuggestHighlightable, AutosuggestRenderer } from './types';
+/**
+ * Check whether item can be highlighted
+ * @param suggestion Suggestion object
+ * @param target item element
+ * @returns highlightable
+ */
+export declare const itemHighlightable: AutosuggestHighlightable;
+/**
+ * Replace forbidden characters in regular expressions
+ * @param string A string to process
+ * @returns clean string
+ */
+export declare const escapeRegExp: (string?: string) => string;
+/**
+ * A basic regexp matching pattern to replace text based on string input.
+ * @param text Value to test against
+ * @param query The query
+ * @param [pattern=<mark>$1</mark>] Provide a pattern to replace string
+ * @returns innerHTML The text that can be used as innerHTML
+ */
+export declare const queryWordSelect: (text: string, query?: string, pattern?: string) => string;
+/**
+ * Update element content
+ * @param el to update content
+ * @param query to search
+ * @param label text to test against
+ * @param value text to use as fallback
+ * @return {void}
+ */
+export declare const updateElementContent: (el: Item, query: string, label: string, value: string | number) => void;
+/**
+ * Build item element from data object
+ * @param suggestion Suggestion data
+ * @param query A query data (usually string, but could be any entity )
+ * @returns item
+ */
+export declare const itemRenderer: AutosuggestRenderer;

package/lib/autosuggest/helpers/utils.js

@@ -0,0 +1,76 @@
+import { Item } from '../../item';
+/**
+ * Check whether item can be highlighted
+ * @param suggestion Suggestion object
+ * @param target item element
+ * @returns highlightable
+ */
+export const itemHighlightable = (suggestion, target) => {
+    return target.highlightable;
+};
+/**
+ * Replace forbidden characters in regular expressions
+ * @param string A string to process
+ * @returns clean string
+ */
+export const escapeRegExp = (string = '') => {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+};
+/**
+ * A basic regexp matching pattern to replace text based on string input.
+ * @param text Value to test against
+ * @param query The query
+ * @param [pattern=<mark>$1</mark>] Provide a pattern to replace string
+ * @returns innerHTML The text that can be used as innerHTML
+ */
+export const queryWordSelect = (text, query = '', pattern = '<mark>$1</mark>') => {
+    query = query && query.trim();
+    if (!query) {
+        return text;
+    }
+    const regExReplace = new RegExp(`(${escapeRegExp(query)})`, 'ig');
+    return text.replace(regExReplace, pattern);
+};
+/**
+ * Update element content
+ * @param el to update content
+ * @param query to search
+ * @param label text to test against
+ * @param value text to use as fallback
+ * @return {void}
+ */
+export const updateElementContent = (el, query, label, value) => {
+    if (itemHighlightable(value, el)) {
+        el.innerHTML = queryWordSelect(label, query);
+    }
+    else {
+        el.label = `${value}`;
+    }
+};
+/**
+ * Build item element from data object
+ * @param suggestion Suggestion data
+ * @param query A query data (usually string, but could be any entity )
+ * @returns item
+ */
+export const itemRenderer = (suggestion, query) => {
+    const el = new Item();
+    if (typeof suggestion === 'object') {
+        const { type, label, title, icon, disabled, value } = suggestion;
+        el.type = type || null;
+        el.disabled = !!disabled;
+        el.icon = icon || null;
+        el.value = value || label || '';
+        if (title) {
+            el.title = title;
+        }
+        updateElementContent(el, query || '', label || '', el.value);
+    }
+    else {
+        const value = suggestion || '';
+        el.label = value;
+        el.value = value;
+        updateElementContent(el, query || '', value, value);
+    }
+    return el;
+};