wj-elements

import { default as WJElement } from '../wje-element/element.js'; import { default as Button } from '../wje-button/button.js'; import { default as Popup } from '../wje-popup/popup.js'; import { default as Icon } from '../wje-icon/icon.js'; import { default as Label } from '../wje-label/label.js'; import { default as Chip } from '../wje-chip/chip.js'; import { default as Input } from '../wje-input/input.js'; import { default as Option } from '../wje-option/option.js'; import { default as Options } from '../wje-options/options.js'; import { default as Checkbox } from '../wje-checkbox/checkbox.js'; /** * `Select` is a custom web component that represents a select input. * @summary This element represents a select input. * @documentation https://elements.webjet.sk/components/select * @status stable * @augments {WJElement} * @slot - The default slot for the select. * @slot anchor - The slot for the anchor. * @slot arrow - The slot for the arrow. * @csspart native - The native select wrapper. * @csspart input - The input field. * @csspart clear - The clear button. * @property {Array} _selected - An array to store selected items. * @property {HTMLElement|null} counterEl - A reference to the counter element, initially null. * @property {ElementInternals} internals - The internal element API for managing state and attributes. * @property {number} maxOptions - The maximum number of options allowed. * @property {boolean} _wasOppened - Tracks whether the select element was previously opened, initially false. * @cssproperty [--wje-select-border-width=1px] - Specifies the width of the border around the select component. Accepts any valid CSS length unit (e.g., `px`, `rem`, `em`). * @cssproperty [--wje-select-border-style=solid] - Defines the style of the border for the select component. Accepts standard CSS border styles, such as `solid`, `dashed`, or `dotted`. * @cssproperty [--wje-select-border-color=var(--wje-border-color)] - Sets the color of the border for the select component. Accepts any valid CSS color value, including color variables, named colors, and hex values. * @cssproperty [--wje-select-options-border-width=1px] - Specifies the width of the border for the select options dropdown. Accepts any valid CSS length unit. * @cssproperty [--wje-select-options-border-style=var(--wje-border-style)] - Defines the border style for the select options dropdown. Inherits from a defined CSS variable for consistency. * @cssproperty [--wje-select-options-border-color=var(--wje-border-color)] - Sets the border color for the select options dropdown. Accepts any valid CSS color value. * @cssproperty [--wje-select-background=var(--wje-background)] - Specifies the background color of the select component. Accepts any valid CSS color value. * @cssproperty [--wje-select-line-height=20px] - Defines the line height for the text within the select component. Accepts any valid CSS length value, ensuring consistent vertical alignment. * @cssproperty [--wje-select-color=var(--wje-color)] - Sets the text color for the select component. Accepts any valid CSS color value. * @cssproperty [--wje-select-border-radius=var(--wje-border-radius-medium)] - Specifies the border radius for the select component.Determines the roundness of the corners and accepts any valid CSS length unit or variable. * @tag wje-select */ export default class Select extends WJElement { /** * Returns the CSS styles for the component. * @static * @returns {CSSStyleSheet} */ static get cssStyleSheet(): CSSStyleSheet; /** * Returns the list of attributes to observe for changes. * @static * @returns {Array<string>} */ static get observedAttributes(): Array<string>; /** * Whether the input is associated with a form. * @type {boolean} */ static formAssociated: boolean; /** * @type {Array} * @description An array to store selected items. */ _selected: any[]; /** * @type {HTMLElement|null} * @description A reference to the counter element, initially null. * @private */ private counterEl; /** * @type {ElementInternals} * @description The internal element API for managing state and attributes. * @private * @readonly * @constant * @default {ElementInternals} this.attachInternals() * @description Attaches the internals to the element. */ private readonly internals; /** * @type {boolean} * @description Tracks whether the select element was previously opened, initially false. * @private * @default {boolean} false */ private _wasOppened; /** * @type {HTMLElement|null} * @description A reference to the native select element, initially null. */ native: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the popup element, initially null. */ popup: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the label element, initially null. */ labelElement: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the slot start element, initially null. */ slotStart: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the slot end element, initially null. */ slotEnd: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the input element, initially null. */ input: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the options wrapper element, initially null. */ optionsWrapper: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the chips element, initially null. */ chips: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the clear button element, initially null. */ clear: HTMLElement | null; /** * @type {HTMLElement|null} * @description A reference to the list element, initially null. */ list: HTMLElement | null; selectedOptions: any[]; /** * An object representing component dependencies with their respective classes. * Each property in the object maps a custom component name (as a string key) * to its corresponding class or constructor. * @typedef {{[key: string]: Function}} Dependencies * @property {Function} 'wje-button' Represents the Button component class. * @property {Function} 'wje-popup' Represents the Popup component class. * @property {Function} 'wje-icon' Represents the Icon component class. * @property {Function} 'wje-label' Represents the Label component class. * @property {Function} 'wje-chip' Represents the Chip component class. * @property {Function} 'wje-input' Represents the Input component class. * @property {Function} 'wje-option' Represents the Option component class. * @property {Function} 'wje-options' Represents the Options component class. * @property {Function} 'wje-checkbox' Represents the Checkbox component class. */ dependencies: { 'wje-button': typeof Button; 'wje-popup': typeof Popup; 'wje-icon': typeof Icon; 'wje-label': typeof Label; 'wje-chip': typeof Chip; 'wje-input': typeof Input; 'wje-option': typeof Option; 'wje-options': typeof Options; 'wje-checkbox': typeof Checkbox; }; /** * Setter for the value attribute. * @param {string} value The value to set. */ set value(value: string); /** * Getter for the value attribute. * @returns {object} The value of the attribute. */ get value(): object; set required(value: boolean); get required(): boolean; /** * Getter for the customErrorDisplay attribute. * @returns {boolean} Whether the attribute is present. */ get customErrorDisplay(): boolean; /** * Getter for the validateOnChange attribute. * @returns {boolean} Whether the attribute is present. */ get validateOnChange(): boolean; /** * Sets the 'invalid' property of the element. * When set to a truthy value, the 'invalid' attribute is added to the element. * When set to a falsy value, the 'invalid' attribute is removed from the element. * @param {boolean} value A boolean indicating whether the element is invalid. */ set invalid(value: boolean); /** * Retrieves the value of the 'invalid' attribute. * This method checks if the 'invalid' attribute is present on the element. * @returns {boolean} Returns true if the 'invalid' attribute is present, otherwise false. */ get invalid(): boolean; /** * Sets the maximum number of options allowed. * @param {string | number | null} value The value to set as the maximum number of options. * If null, the 'max-options' attribute will be removed. */ set maxOptions(value: string | number | null); /** * Retrieves the maximum number of options allowed. * Parses the value of the 'max-options' attribute from the element and converts it to a number. * If the attribute is not present or cannot be converted to a valid number, defaults to 1. * @returns {number} The maximum number of options, or 0 if the attribute is not set or invalid. */ get maxOptions(): number; /** * Getter for the form attribute. * @returns {HTMLFormElement} The form the input is associated with. */ get form(): HTMLFormElement; /** * Getter for the name attribute. * @returns {string} The name of the input. */ get name(): string; /** * Getter for the type attribute. * @returns {string} The type of the input. */ get type(): string; /** * Getter for the validity attribute. * @returns {ValidityState} The validity state of the input. */ get validity(): ValidityState; /** * Getter for the validationMessage attribute. * @returns {string} The validation message of the input. */ get validationMessage(): string; /** * Getter for the willValidate attribute. * @returns {boolean} Whether the input will be validated. */ get willValidate(): boolean; /** * @summary Setter for the defaultValue attribute. * This method sets the 'value' attribute of the custom input element to the provided value. * The 'value' attribute represents the default value of the input element. * @param {string} value The value to set as the default value. */ set defaultValue(value: string); /** * @summary Getter for the defaultValue attribute. * This method retrieves the 'value' attribute of the custom input element. * The 'value' attribute represents the default value of the input element. * If the 'value' attribute is not set, it returns an empty string. * @returns {string} The default value of the input element. */ get defaultValue(): string; /** * Sets the label value. * @param {Array} value The selected value to set. */ set selected(value: any[]); /** * Returns the selected value. * @returns {Array} The selected value. */ get selected(): any[]; /** * Retrieves the complete list of options available for the component. * The options are determined by combining elements from various sources, including loaded options, added options, and HTML-sourced options. * If a `wje-options` element is present within the component, its loaded options are included in the merged list. * In the absence of a `wje-options` element, duplicates among the added and HTML options are removed, retaining their order. * @returns {Array<object>} An array containing all the available options, combining the loaded, added, and HTML-based options, with duplicates removed where applicable. */ get options(): Array<object>; /** * Sets the trigger value. * @param {string} value The trigger value to set. */ set trigger(value: string); /** * Returns the trigger value. * @returns {string} The trigger value. */ get trigger(): string; set offset(value: string); get offset(): string; /** * Draws the component for the select. * @returns {DocumentFragment} */ draw(): DocumentFragment; findEl: HTMLElement; /** * Performs actions and binds events after the component's markup and state are initialized. * Actions include setting up event listeners, managing option elements, handling focus and blur behaviors, * synchronizing the selected options, and managing a find functionality for filtering options. * @returns {void} Does not return a value. The method operates by updating the state and behavior of the component. */ afterDraw(): void; pristine: boolean; /** * Handles the option change event. * @param {Event} e The event. */ optionChange: (e: Event) => void; /** * Handles the selection and deselection of an option element. * @param {HTMLElement} option The option element that was clicked. * @param {boolean} [multiple] Indicates whether multiple selection is allowed. */ processClickedOption: (option: HTMLElement, multiple?: boolean) => void; /** * Filters out a specified option from the `selectedOptions` array. * This function removes an option from the `selectedOptions` array if its value * matches the value of the option provided as an argument. It allows for dynamically * updating the selected options by excluding the specified option. * @param {object} option The option to be removed from the `selectedOptions` array. * Should be an object containing a `value` property that is compared to the * `value` property of objects in the `selectedOptions` array. */ filterOutOption: (option: object) => void; /** * Returns all the options as HTML. * @returns {NodeList} The options as HTML. */ getAllOptions(): NodeList; /** * Returns the selected options as HTML. * @returns {NodeList} The selected options as HTML. */ getSelectedOptions(): NodeList; /** * Returns the selected options. * @returns {Array} The selected options. */ getSelected(): any[]; /** * Handles the selection change. * @param {Element[]} options The option that changed. * @param {number} length The length of the selected options. */ selectionChanged(options?: Element[], length?: number): void; /** * Updates the selected options and their corresponding chips. * @param {boolean} [silence] Determines whether to suppress the "wje-select:change" event. * @returns {void} * @description * This method fetches the currently selected options and updates the `selectedOptions` array. * It clears and rebuilds the chips representing the selected items in the UI. * If the number of selected options reaches the maximum allowed (`maxOptions`), it stops updating the counter. * Optionally, it dispatches a custom event when the selection changes unless `silence` is set to `true`. * //@fires wje-select:change - Dispatched when the selection changes, unless `silence` is `true`. * @example * // Call the method and allow event dispatch * selections(); * @example * // Call the method without dispatching the event * selections(true); */ selections(silence?: boolean): void; /** * Manages the display of a counter element to indicate the number of items exceeding the maximum allowed options. * - If the number of selected items equals the maximum allowed, the counter element is removed. * - If the counter element doesn't exist and the number of items exceeds the maximum, it is created and updated. */ counter(): void; /** * Returns a chip element. * @param {Element} option The option to get the chip for. * @returns {Element} The chip element. */ getChip(option: Element): Element; /** * Handles the chip remove event. * @param {Event} e The event. */ removeChip: (e: Event) => void; /** * Generates an HTML option element based on the provided item and mapping. * @param {object} item The item to generate the option for. * @param {object} [map] The mapping object that specifies the properties of the item to use for the option's value and text. * @param {string} [map.value] The property of the item to use for the option's value. * @param {string} [map.text] The property of the item to use for the option's text. * @returns {HTMLElement} The generated HTML option element. */ htmlOption(item: object, map?: { value?: string; text?: string; }): HTMLElement; /** * Adds an option to the select element. * @param {any} optionData The data for the option to be added. * @param {boolean} [silent] Whether to suppress any events triggered by the addition of the option. * @param {object} [map] The mapping object specifying the properties of the option data to be used for the value and text of the option. */ addOption(optionData: any, silent?: boolean, map?: object): void; /** * Adds options to the select element. * @param {Array | object} optionsData The options data to be added. Can be an array of objects or a single object. * @param {boolean} [silent] Indicates whether to trigger events when adding options. Default is false. * @param {object} [map] The mapping object that specifies the properties of the options data object. Default is { value: "value", text: "text" }. */ addOptions(optionsData: any[] | object, silent?: boolean, map?: object): void; /** * Selects an option with the specified value. * @param {string} value The value of the option to be selected. * @param {boolean} [silent] Whether to suppress firing events. */ selectOption(value: string, silent?: boolean): void; /** * Selects one or multiple options in the select element. * @param {Array|any} values The value(s) of the option(s) to be selected. * @param {boolean} [silent] Whether to trigger the change event or not. */ selectOptions(values: any[] | any, silent?: boolean): void; /** * Returns the provided item. * @param {any} item The item to be returned. * @returns {any} The same item that was passed as input. */ htmlSelectedItem(item: any): any; /** * Clones and appends an icon from a template with slot "check" to the given option element. * @param {HTMLElement} option The target option element where the "check" icon will be added. * @returns {void} */ optionCheckSlot(option: HTMLElement): void; /** * Validates the selection of options in the select element. * Checks if the element is required and no option is selected, * in which case it sets a validation error with a custom message. * If the element passes validation, it clears any existing validation errors. * * @return {void} Does not return a value. */ validateSelect(): void; /** * Checks and updates the validation state of the component based on its current properties. * If the component is invalid and a custom error display is enabled, it dispatches an 'invalid' event. * @returns {void} This method does not return a value. */ propagateValidation(): void; showInvalidMessage(): void; /** * Lifecycle callback invoked when the custom element becomes associated with a form element. * @param {HTMLFormElement} form The form element the custom element is associated with. * @returns {void} */ formAssociatedCallback(form: HTMLFormElement): void; /** * The formResetCallback method is a built-in lifecycle callback that gets called when a form gets reset. * This method is responsible for resetting the value of the custom input element to its default value. * It also resets the form value and validity state in the form internals. * @function */ formResetCallback(): void; /** * The formStateRestoreCallback method is a built-in lifecycle callback that gets called when the state of a form-associated custom element is restored. * This method is responsible for restoring the value of the custom input element to its saved state. * It also restores the form value and validity state in the form internals to their saved states. * @param {object} state The saved state of the custom input element. * @function */ formStateRestoreCallback(state: object): void; /** * The formStateSaveCallback method is a built-in lifecycle callback that gets called when the state of a form-associated custom element is saved. * This method is responsible for saving the value of the custom input element. * @returns {object} The saved state of the custom input element. * @function */ formStateSaveCallback(): object; /** * The formDisabledCallback method is a built-in lifecycle callback that gets called when the disabled state of a form-associated custom element changes. * This method is not implemented yet. * @param {boolean} disabled The new disabled state of the custom input element. * @function */ formDisabledCallback(disabled: boolean): void; /** * Checks if all elements in the `elements` array are present in the `options` array based on their `option` property. * @param {Array} elements The array of elements to check. Each element should have an `option` property. * @param {Array} options The array of options to verify against. * @returns {boolean} Returns true if all elements in the `elements` array are found within the `options` array, otherwise returns false. */ areAllElementsInOptions(elements: any[], options: any[]): boolean; #private; }