@ui5/webcomponents 0.0.0-cb061e041 → 0.0.0-cddf8ba1c

package/dist/Select.d.ts

@@ -8,32 +8,59 @@ import "@ui5/webcomponents-icons/dist/information.js";
 import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import "@ui5/webcomponents-icons/dist/decline.js";
 import type { Timeout } from "@ui5/webcomponents-base/dist/types.js";
-import type { ClickEventDetail } from "./List.js";
+import type { ListItemClickEventDetail } from "./List.js";
 import Option from "./Option.js";
 import ResponsivePopover from "./ResponsivePopover.js";
 import Popover from "./Popover.js";
 import type { IFormElement } from "./features/InputElementsFormSupport.js";
 import type ListItemBase from "./ListItemBase.js";
+import type SelectMenu from "./SelectMenu.js";
+import type { SelectMenuOptionClick, SelectMenuChange } from "./SelectMenu.js";
 type SelectChangeEventDetail = {
-    selectedOption: Option;
+    selectedOption: IOption;
+};
+type SelectLiveChangeEventDetail = {
+    selectedOption: IOption;
 };
 interface IOption extends UI5Element {
+    id: string;
     selected: boolean;
-    _focused: boolean;
+    _focused?: boolean;
+    focused?: boolean;
     icon?: string | undefined;
     value: string;
     textContent: string | null;
     title: string;
-    additionalText: string;
-    id: string;
-    stableDomRef: string;
+    additionalText?: string;
+    stableDomRef?: string;
+    displayText?: string;
 }
 /**
  * @class
  *
  * <h3 class="comment-api-title">Overview</h3>
+ *
  * The <code>ui5-select</code> component is used to create a drop-down list.
- * The items inside the <code>ui5-select</code> define the available options by using the <code>ui5-option</code> component.
+ *
+ * <h3>Usage</h3>
+ *
+ * There are two main usages of the <code>ui5-select></code>.
+ *
+ * 1. With Option (<code>ui5-option</code>) web component:
+ * <br>
+ * The available options of the Select are defined by using the Option component.
+ * The Option comes with predefined design and layout, including <code>icon</code>, <code>text</code> and <code>additional-text</code>.
+ * <br><br>
+ *
+ * 2. With SelectMenu (<code>ui5-select-menu</code>) and SelectMenuOption (<code>ui5-select-menu-option</code>) web components:
+ * <br>
+ * The SelectMenu can be used as alternative to define the Select's dropdown
+ * and can be used via the <code>menu</code> property of the Select to reference SelectMenu by its ID.
+ * The component gives the possibility to customize the Select's dropdown
+ * by slotting entirely custom options (via the SelectMenuOption component) and adding custom styles.
+ *
+ * <b>Note:</b> SelectMenu is a popover and placing it top-level in the HTML page is recommended,
+ * because some page styles (for example transitions) can misplace the SelectMenu.
  *
  * <h3>Keyboard Handling</h3>
  * The <code>ui5-select</code> provides advanced keyboard handling.
@@ -57,12 +84,25 @@ interface IOption extends UI5Element {
  * @alias sap.ui.webc.main.Select
  * @extends sap.ui.webc.base.UI5Element
  * @tagname ui5-select
- * @appenddocs sap.ui.webc.main.Option
+ * @appenddocs sap.ui.webc.main.Option sap.ui.webc.main.SelectMenu sap.ui.webc.main.SelectMenuOption
  * @public
  * @since 0.8.0
  */
 declare class Select extends UI5Element implements IFormElement {
     static i18nBundle: I18nBundle;
+    /**
+     * Defines a reference (ID or DOM element) of component's menu of options
+     * as alternative to define the select's dropdown.
+     * <br><br>
+     * <b>Note:</b> Usage of <code>ui5-select-menu</code> is recommended.
+     *
+     * @type {sap.ui.webc.base.types.DOMReference}
+     * @defaultvalue undefined
+     * @name sap.ui.webc.main.Select.prototype.menu
+     * @public
+     * @since 1.17.0
+     */
+    menu?: HTMLElement | string;
     /**
      * Defines whether the component is in disabled state.
      * <br><br>
@@ -95,22 +135,13 @@ declare class Select extends UI5Element implements IFormElement {
     name: string;
     /**
      * Defines the value state of the component.
-     * <br><br>
-     * Available options are:
-     * <ul>
-     * <li><code>None</code></li>
-     * <li><code>Error</code></li>
-     * <li><code>Warning</code></li>
-     * <li><code>Success</code></li>
-     * <li><code>Information</code></li>
-     * </ul>
      *
      * @type {sap.ui.webc.base.types.ValueState}
      * @defaultvalue "None"
      * @name sap.ui.webc.main.Select.prototype.valueState
      * @public
      */
-    valueState: ValueState;
+    valueState: `${ValueState}`;
     /**
      * Defines whether the component is required.
      *
@@ -121,6 +152,19 @@ declare class Select extends UI5Element implements IFormElement {
      * @public
      */
     required: boolean;
+    /**
+     * Defines whether the component is read-only.
+     * <br><br>
+     * <b>Note:</b> A read-only component is not editable,
+     * but still provides visual feedback upon user interaction.
+     *
+     * @type {boolean}
+     * @name sap.ui.webc.main.Select.prototype.readonly
+     * @defaultvalue false
+     * @since 1.21.0
+     * @public
+     */
+    readonly: boolean;
     /**
      * Defines the accessible ARIA name of the component.
      *
@@ -163,17 +207,21 @@ declare class Select extends UI5Element implements IFormElement {
      * @private
      */
     focused: boolean;
-    _syncedOptions: Array<IOption>;
+    /**
+     * @type {sap.ui.webc.base.types.Integer}
+     * @private
+     */
     _selectedIndex: number;
+    _syncedOptions: Array<IOption>;
     _selectedIndexBeforeOpen: number;
     _escapePressed: boolean;
-    _lastSelectedOption: Option | null;
+    _lastSelectedOption: IOption | null;
     _typedChars: string;
     _typingTimeoutID?: Timeout | number;
     responsivePopover: ResponsivePopover;
     selectedItem?: string | null;
-    popover?: Popover;
-    value: string;
+    valueStatePopover?: Popover;
+    selectMenu?: SelectMenu;
     /**
      * Defines the component options.
      *
@@ -214,6 +262,32 @@ declare class Select extends UI5Element implements IFormElement {
      * @public
     */
     valueStateMessage: Array<HTMLElement>;
+    /**
+     * Defines the HTML element that will be displayed in the component input part,
+     * representing the selected option.
+     * <br><br>
+     *
+     * <b>Note:</b> If not specified and <code>ui5-select-menu-option</code> is used,
+     * either the option's <code>display-text</code> or its textContent will be displayed.
+     * <br><br>
+     *
+     * <b>Note:</b> If not specified and <code>ui5-option</code> is used,
+     * the option's textContent will be displayed.
+     *
+     * @type {HTMLElement[]}
+     * @name sap.ui.webc.main.Select.prototype.label
+     * @slot label
+     * @public
+     * @since 1.17.0
+    */
+    label: Array<HTMLElement>;
+    _onMenuClick: (e: CustomEvent<SelectMenuOptionClick>) => void;
+    _onMenuClose: () => void;
+    _onMenuOpen: () => void;
+    _onMenuBeforeOpen: () => void;
+    _onMenuChange: (e: CustomEvent<SelectMenuChange>) => void;
+    _attachMenuListeners: (menu: HTMLElement) => void;
+    _detachMenuListeners: (menu: HTMLElement) => void;
     constructor();
     onBeforeRendering(): void;
     onAfterRendering(): void;
@@ -221,6 +295,26 @@ declare class Select extends UI5Element implements IFormElement {
     _onfocusout(): void;
     get _isPickerOpen(): boolean;
     _respPopover(): Promise<ResponsivePopover>;
+    /**
+     * Defines the value of the component:
+     * <br>
+     * - when get - returns the value of the component, e.g. the <code>value</code> property of the selected option or its text content.
+     * <br>
+     * - when set - selects the option with matching <code>value</code> property or text content.
+     * <br><br>
+     * <b>Note:</b> If the given value does not match any existing option,
+     * the first option will get selected.
+     *
+     * @public
+     * @type { string }
+     * @defaultvalue ""
+     * @name sap.ui.webc.main.Select.prototype.value
+     * @since 1.20.0
+     * @formProperty
+     * @formEvents change liveChange
+     */
+    set value(newValue: string);
+    get value(): string;
     /**
      * Currently selected <code>ui5-option</code> element.
      * @readonly
@@ -228,15 +322,25 @@ declare class Select extends UI5Element implements IFormElement {
      * @name sap.ui.webc.main.Select.prototype.selectedOption
      * @public
      */
-    get selectedOption(): Option | undefined;
+    get selectedOption(): IOption | undefined;
+    onMenuClick(e: CustomEvent<SelectMenuOptionClick>): void;
+    onMenuBeforeOpen(): void;
+    onMenuOpen(): void;
+    onMenuClose(): void;
+    onMenuChange(e: CustomEvent<SelectMenuChange>): void;
+    _toggleSelectMenu(): void;
+    onExitDOM(): void;
     _toggleRespPopover(): Promise<void>;
     _attachRealDomRefs(): Promise<void>;
     _syncSelection(): void;
+    _getSelectMenu(): SelectMenu | undefined;
+    attachMenuListeners(menu: HTMLElement): void;
+    detachMenuListeners(menu: HTMLElement): void;
     _enableFormSupport(): void;
     _onkeydown(e: KeyboardEvent): void;
     _handleKeyboardNavigation(e: KeyboardEvent): void;
     _selectTypedItem(text: string): void;
-    _searchNextItemByText(text: string): Option | undefined;
+    _searchNextItemByText(text: string): IOption | undefined;
     _handleHomeKey(e: KeyboardEvent): void;
     _handleEndKey(e: KeyboardEvent): void;
     _onkeyup(e: KeyboardEvent): void;
@@ -246,7 +350,7 @@ declare class Select extends UI5Element implements IFormElement {
      * The user clicked on an item from the list
      * @private
      */
-    _handleItemPress(e: CustomEvent<ClickEventDetail>): void;
+    _handleItemPress(e: CustomEvent<ListItemClickEventDetail>): void;
     _itemMousedown(e: MouseEvent): void;
     _onclick(): void;
     /**
@@ -254,6 +358,7 @@ declare class Select extends UI5Element implements IFormElement {
      * @private
      */
     _handleSelectionChange(index?: number): void;
+    _scrollSelectedItem(): void;
     _handleArrowNavigation(e: KeyboardEvent): void;
     _changeSelectedItem(oldIndex: number, newIndex: number): void;
     _getNextOptionIndex(): number;
@@ -261,7 +366,9 @@ declare class Select extends UI5Element implements IFormElement {
     _beforeOpen(): void;
     _afterOpen(): void;
     _afterClose(): void;
-    _fireChangeEvent(selectedOption: Option): void;
+    get selectOptions(): Array<IOption>;
+    get hasCustomLabel(): boolean;
+    _fireChangeEvent(selectedOption: IOption): void;
     get valueStateTextMappings(): {
         Success: string;
         Information: string;
@@ -281,8 +388,8 @@ declare class Select extends UI5Element implements IFormElement {
     get valueStateTextId(): string | undefined;
     get isDisabled(): true | undefined;
     get _headerTitleText(): string;
-    get _currentlySelectedOption(): Option;
-    get _effectiveTabIndex(): "0" | "-1";
+    get _currentlySelectedOption(): IOption;
+    get _effectiveTabIndex(): "-1" | "0";
     /**
     * This method is relevant for sap_horizon theme only
     */
@@ -329,4 +436,4 @@ declare class Select extends UI5Element implements IFormElement {
     static onDefine(): Promise<void>;
 }
 export default Select;
-export type { SelectChangeEventDetail, IOption, };
+export type { SelectChangeEventDetail, SelectLiveChangeEventDetail, IOption, };