@synergy-design-system/components
Version:
This package provides the base of the Synergy Design System as native web components. It uses [lit](https://www.lit.dev) and parts of [shoelace](https://shoelace.style/). Synergy officially supports the latest two versions of all major browsers (as define
210 lines (209 loc) • 10.2 kB
TypeScript
/**
* ---------------------------------------------------------------------
* 🔒 AUTOGENERATED BY VENDORISM
* Removing this comment will prevent it from being managed by it.
* ---------------------------------------------------------------------
*/
import SynergyElement from '../../internal/synergy-element.js';
import SynIcon from '../icon/icon.component.js';
import SynPopup from '../popup/popup.component.js';
import SynTag from '../tag/tag.component.js';
import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
import type { SynergyFormControl } from '../../internal/synergy-element.js';
import type SynOption from '../option/option.component.js';
/**
* @summary Selects allow you to choose items from a menu of predefined options.
* @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-select--docs
* @status stable
* @since 2.0
*
* @dependency syn-icon
* @dependency syn-popup
* @dependency syn-tag
*
* @slot - The listbox options. Must be `<syn-option>` elements. You can use `<syn-divider>` to group items visually.
* @slot label - The input's label. Alternatively, you can use the `label` attribute.
* @slot prefix - Used to prepend a presentational icon or similar element to the combobox.
* @slot suffix - Used to append a presentational icon or similar element to the combobox.
* @slot clear-icon - An icon to use in lieu of the default clear icon.
* @slot expand-icon - The icon to show when the control is expanded and collapsed. Rotates on open and close.
* @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
*
* @event syn-change - Emitted when the control's value changes.
* @event syn-clear - Emitted when the control's value is cleared.
* @event syn-input - Emitted when the control receives input.
* @event syn-focus - Emitted when the control gains focus.
* @event syn-blur - Emitted when the control loses focus.
* @event syn-show - Emitted when the select's menu opens.
* @event syn-after-show - Emitted after the select's menu opens and all animations are complete.
* @event syn-hide - Emitted when the select's menu closes.
* @event syn-after-hide - Emitted after the select's menu closes and all animations are complete.
* @event syn-invalid - Emitted when the form control has been checked for validity and its constraints aren't satisfied.
*
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The select's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart combobox - The container the wraps the prefix, suffix, combobox, clear icon, and expand button.
* @csspart prefix - The container that wraps the prefix slot.
* @csspart suffix - The container that wraps the suffix slot.
* @csspart display-input - The element that displays the selected option's label, an `<input>` element.
* @csspart listbox - The listbox container where options are slotted.
* @csspart tags - The container that houses option tags when `multiselect` is used.
* @csspart tag - The individual tags that represent each multiselect option.
* @csspart tag__base - The tag's base part.
* @csspart tag__content - The tag's content part.
* @csspart tag__remove-button - The tag's remove button.
* @csspart tag__remove-button__base - The tag's remove button base part.
* @csspart clear-button - The clear button.
* @csspart expand-icon - The container that wraps the expand icon.
* @csspart popup - The popup's exported `popup` part. Use this to target the tooltip's popup container.
*/
export default class SynSelect extends SynergyElement implements SynergyFormControl {
static styles: CSSResultGroup;
static dependencies: {
'syn-icon': typeof SynIcon;
'syn-popup': typeof SynPopup;
'syn-tag': typeof SynTag;
};
private readonly formControlController;
private readonly hasSlotController;
private readonly localize;
private isInitialized;
private typeToSelectString;
private typeToSelectTimeout;
private closeWatcher;
private resizeObserver;
popup: SynPopup;
combobox: HTMLSlotElement;
displayInput: HTMLInputElement;
valueInput: HTMLInputElement;
listbox: HTMLSlotElement;
tagContainer: HTMLDivElement;
private hasFocus;
displayLabel: string;
currentOption: SynOption;
selectedOptions: SynOption[];
private valueHasChanged;
/**
* The delimiter to use when setting the value when `multiple` is enabled.
* The default is a space, but you can set it to a comma or other character.
* @example <syn-select delimiter="|" value="option-1|option-2"></syn-select>
*/
delimiter: string;
/** The name of the select, submitted as a name/value pair with form data. */
name: string;
private _value;
get value(): string | number | Array<string | number>;
/**
* The current value of the select, submitted as a name/value pair with form data. When `multiple` is enabled, the
* value attribute will be a space-delimited list of values based on the options selected, and the value property will
* be an array. **For this reason, values must not contain spaces.**
*/
set value(val: string | number | Array<string | number>);
/** The default value of the form control. Primarily used for resetting the form control. */
defaultValue: string | number | Array<string | number>;
/** The select's size. */
size: 'small' | 'medium' | 'large';
/** Placeholder text to show as a hint when the select is empty. */
placeholder: string;
/** Allows more than one option to be selected. */
multiple: boolean;
/**
* The maximum number of selected options to show when `multiple` is true. After the maximum, "+n" will be shown to
* indicate the number of additional items that are selected. Set to 0 to remove the limit.
*/
maxOptionsVisible: number;
/** Disables the select control. */
disabled: boolean;
/** Adds a clear button when the select is not empty. */
clearable: boolean;
/**
* Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can
* use the `show()` and `hide()` methods and this attribute will reflect the select's open state.
*/
open: boolean;
/**
* Enable this option to prevent the listbox from being clipped when the component is placed inside a container with
* `overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.
*/
hoist: boolean;
/** The select's label. If you need to display HTML, use the `label` slot instead. */
label: string;
/**
* The preferred placement of the select's menu. Note that the actual placement may vary as needed to keep the listbox
* inside of the viewport.
*/
placement: 'top' | 'bottom';
/** The select's help text. If you need to display HTML, use the `help-text` slot instead. */
helpText: string;
/**
* By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you
* to place the form control outside of a form and associate it with the form that has this `id`. The form must be in
* the same document or shadow root for this to work.
*/
form: string;
/** The select's required attribute. */
required: boolean;
/**
* A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second
* is the current tag's index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at
* the specified value.
*/
getTag: (option: SynOption, index: number) => TemplateResult | string | HTMLElement;
/** Gets the validity state object */
get validity(): ValidityState;
/** Gets the validation message */
get validationMessage(): string;
private enableResizeObserver;
connectedCallback(): void;
disconnectedCallback(): void;
private addOpenListeners;
private removeOpenListeners;
private handleFocus;
private handleBlur;
private handleDocumentFocusIn;
private handleDocumentKeyDown;
private handleDocumentMouseDown;
private handleLabelClick;
private handleComboboxMouseDown;
private handleComboboxKeyDown;
private handleClearClick;
private handleClearMouseDown;
private handleOptionClick;
handleDefaultSlotChange(): void;
private handleTagRemove;
private getAllOptions;
private getFirstOption;
private setCurrentOption;
private setSelectedOptions;
private toggleOptionSelection;
private selectionChanged;
protected get tags(): TemplateResult<1>[];
private handleInvalid;
handleDelimiterChange(): void;
handleDisabledChange(): void;
firstUpdated(): void;
protected updated(changedProperties: PropertyValues<this>): void;
protected willUpdate(changedProperties: PropertyValues): void;
attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
handleValueChange(): void;
handleOpenChange(): Promise<void>;
/** Shows the listbox. */
show(): Promise<void>;
/** Hides the listbox. */
hide(): Promise<void>;
/** Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid. */
checkValidity(): boolean;
/** Gets the associated form, if one exists. */
getForm(): HTMLFormElement | null;
/** Checks for validity and shows the browser's validation message if the control is invalid. */
reportValidity(): boolean;
/** Sets a custom validation message. Pass an empty string to restore validity. */
setCustomValidity(message: string): void;
/** Sets focus on the control. */
focus(options?: FocusOptions): void;
/** Removes focus from the control. */
blur(): void;
render(): TemplateResult<1>;
}