@refinitiv-ui/elements 0.0.0-build.1957399501.1

package/lib/autosuggest/custom-elements.md

@@ -0,0 +1,54 @@
+# ef-autosuggest
+
+Shows suggestions based on users' query.
+It can be used by attaching to text form control
+such as TextField, Multi Input, etc.
+Autosuggest supports various use cases such as
+custom rendering, pagination, asynchronous data request, etc.
+
+## Properties
+
+| Property         | Attribute          | Type                                         | Default                | Description                                      |
+|------------------|--------------------|----------------------------------------------|------------------------|--------------------------------------------------|
+| `attach`         | `attach`           | `AutosuggestTargetElement \| string \| null` | null                   | An HTML Element or CSS selector                  |
+| `debounceRate`   | `debounce-rate`    | `number`                                     | "100"                  | Debounce rate in ms of the filter as a number.<br />Used to throttle the filter rate so as not to trigger unneeded filtering |
+| `highlightable`  |                    | `AutosuggestHighlightable`                   | "itemHighlightable"    | A function that is applied to every suggestion during the render process<br />to say whether the item can be highlighted and selected. Only items that return true are considered.<br />By default the function checks for `item` `highlightable` property. |
+| `htmlRenderer`   | `html-renderer`    | `boolean`                                    | false                  | If set to true, the render function is not called. Instead the wrapper element<br />should populate and destroy suggestion elements. Rendering items manually<br />may have performance benefits in frameworks that use virtual DOM (such as `Vue`, `React`, `hyperHTML` and others) |
+| `loading`        | `loading`          | `boolean`                                    | false                  | If set to true show loading mask                 |
+| `moreResults`    | `more-results`     | `boolean`                                    | false                  | If set to true display 'Has more results' item   |
+| `moreSearchText` | `more-search-text` | `string`                                     | "More results for {0}" | Custom text for More Search                      |
+| `opened`         | `opened`           | `boolean`                                    | false                  | Auto suggest popup's open state                  |
+| `query`          |                    | `AutosuggestQuery \| null`                   | null                   | An object that represents a query from attach target |
+| `renderer`       |                    | `AutosuggestRenderer`                        | "itemRenderer"         | A renderer applied to suggestion.<br />By default a render maps data to item attributes |
+| `requestOnFocus` | `request-on-focus` | `boolean`                                    | false                  | Request suggestions when attach target is focused |
+| `suggestions`    |                    | `AutosuggestItem[]`                          | []                     | A list of suggestion items                       |
+
+## Methods
+
+| Method               | Type                 | Description                                      |
+|----------------------|----------------------|--------------------------------------------------|
+| `onInputBlur`        | `(event: any): void` | Run when input has lost focus<br /><br />**event**: by default `blur` event is listened |
+| `onInputFocus`       | `(event: any): void` | Run when input received focus<br /><br />**event**: by default `focus` event is listened |
+| `onInputKeyDown`     | `(event: any): void` | Run when input key down event has happened<br /><br />**event**: by default `keydown` event is listened |
+| `onInputValueChange` | `(event: any): void` | Run when attach target value changes.<br /><br />**event**: by default `value-changed` event is listened |
+| `refit`              | `(): void`           | Set the width                                    |
+
+## Events
+
+| Event                         | Description                                      |
+|-------------------------------|--------------------------------------------------|
+| `add-attach-target-events`    | Fired when attach has been set                   |
+| `item-highlight`              | Fired when an item gets highlighted or highlight is removed |
+| `item-select`                 | Fired when an item gets selected                 |
+| `remove-attach-target-events` | Fired when attach has been removed               |
+| `suggestions-changed`         | Fired when suggestions changed                   |
+| `suggestions-clear-requested` | Fired when auto suggest requests to clear the data. If used in reactive application, prevent default and set suggestions to [] |
+| `suggestions-fetch-requested` | Fired when auto suggest requests the data        |
+| `suggestions-query`           | Fired when input value has changed and the query must be set |
+
+## Slots
+
+| Name     | Description                                      |
+|----------|--------------------------------------------------|
+| `footer` | Slot to add custom contents at the bottom of autosuggest popup |
+| `header` | Slot to add custom contents at the top of autosuggest popup |

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

@@ -0,0 +1,54 @@
+import type { 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 type { Item } from '../../item';
+import type { 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,75 @@
+/**
+ * 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 = document.createElement('ef-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;
+};