@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
241 lines (240 loc) • 10.8 kB
TypeScript
import type { CSSResultGroup, PropertyValues } from 'lit';
import SynergyElement from '../../internal/synergy-element.js';
import SynIcon from '../icon/icon.component.js';
import SynPopup from '../popup/popup.component.js';
import type { SynergyFormControl } from '../../internal/synergy-element.js';
import SynOption from '../option/option.component.js';
import { type OptionRenderer } from './option-renderer.js';
/**
* @summary Comboboxes allow you to choose items from a menu of predefined options.
* @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-combobox--docs
* @status stable
*
* @dependency syn-icon
* @dependency syn-popup
*
* @slot - The listbox options. Must be `<syn-option>` elements.
* You can use `<syn-optgroup>`'s to group items visually.
* @slot label - The combobox'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 combobox.
* 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 combobox's menu opens.
* @event syn-after-show - Emitted after the combobox's menu opens and all animations are complete.
* @event syn-hide - Emitted when the combobox's menu closes.
* @event syn-after-hide - Emitted after the combobox'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.
* @event syn-error - Emitted when the combobox menu fails to open.
*
* @csspart form-control - The form control that wraps the label, combobox, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The combobox's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart combobox - The container the wraps the prefix, 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 the options are slotted
* and the filtered options list exists.
* @csspart filtered-listbox - The container that wraps the filtered options.
* @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.
* @csspart no-results - The container that wraps the "no results" message.
*
* @animation combobox.show - The animation to use when showing the combobox.
* @animation combobox.hide - The animation to use when hiding the combobox.
*/
export default class SynCombobox extends SynergyElement implements SynergyFormControl {
static styles: CSSResultGroup;
static dependencies: {
'syn-icon': typeof SynIcon;
'syn-popup': typeof SynPopup;
};
private readonly formControlController;
private readonly hasSlotController;
private readonly localize;
private closeWatcher;
/** The last syn-option, that was selected by click or via keyboard navigation */
private lastOption;
private isOptionRendererTriggered;
private isInitialized;
popup: SynPopup;
combobox: HTMLSlotElement;
displayInput: HTMLInputElement;
valueInput: HTMLInputElement;
listbox: HTMLSlotElement;
private defaultSlot;
private hasFocus;
private isUserInput;
displayLabel: string;
selectedOption: SynOption | undefined;
numberFilteredOptions: number;
cachedOptions: SynOption[];
/** The name of the combobox, submitted as a name/value pair with form data. */
name: string;
/**
* The current value of the combobox, submitted as a name/value pair with form data.
*/
value: string;
/** The default value of the form control. Primarily used for resetting the form control. */
defaultValue: string;
/** The combobox's size. */
size: 'small' | 'medium' | 'large';
/** Placeholder text to show as a hint when the combobox is empty. */
placeholder: string;
/** Disables the combobox control. */
disabled: boolean;
/** Adds a clear button when the combobox is not empty. */
clearable: boolean;
/**
* Indicates whether or not the combobox is open.
* You can toggle this attribute to show and hide the listbox, or you can use the `show()`
* and `hide()` methods and this attribute will reflect the combobox'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 combobox's label. If you need to display HTML, use the `label` slot instead. */
label: string;
/**
* The preferred placement of the combobox's menu.
* Note that the actual placement may vary as needed to keep the listbox inside of the viewport.
*/
placement: 'top' | 'bottom';
/** The combobox'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 combobox's required attribute. */
required: boolean;
/**
* When set to `true`, restricts the combobox to only allow selection from the available options.
* Users will not be able to enter custom values that are not present in the list.
*/
restricted: boolean;
/**
* A function that customizes the rendered option. The first argument is the option, the second
* is the query string, which is typed into the combobox.
* The function should return either a Lit TemplateResult or a string containing trusted HTML
* to render in the shown list of filtered options.
* If the query string should be highlighted use the `highlightOptionRenderer` function.
*/
getOption: OptionRenderer;
/**
* A function used to filter options in the combobox component.
* The default filter method is a case- and diacritic-insensitive string comparison.
*
* @param option - The option to be filtered.
* @param queryString - The query string used for filtering.
* @returns A boolean indicating whether the option should be included in the filtered results.
*/
filter: (option: SynOption, queryString: string) => boolean;
/** Gets the validity state object */
get validity(): ValidityState;
/** Gets the validation message */
get validationMessage(): string;
connectedCallback(): void;
firstUpdated(): void;
protected willUpdate(changedProperties: PropertyValues): void;
private addOpenListeners;
private removeOpenListeners;
private handleFocus;
private handleBlur;
private handleDocumentFocusIn;
private handleDocumentKeyDown;
private handleDocumentMouseDown;
private handleLabelClick;
private handleComboboxMouseDown;
private handleComboboxKeyDown;
private handleClearClick;
private clearCombobox;
private preventLoosingFocus;
private handleOptionClick;
/**
* Selects the following or previous option.
*
* @param isNext - A boolean indicating whether to select the following option (true)
* or the previous option (false).
*/
private selectNextOption;
private getAllFilteredOptions;
private getCurrentOption;
private setCurrentOption;
/**
* Updates the selected options cache, the current value, and the display value
*/
private updateSelectedOptionsCacheAndValue;
private setSelectedOptionToSelected;
private handleInvalid;
handlePropertiesChange(): void;
handleDisabledChange(): void;
handleValueChange(): void;
handleOpenChange(): Promise<void>;
/**
* Shows the listbox. If it is not possible to open the listbox, because there are no
* appropriate filtered options, a syn-error is emitted and the listbox stays closed.
*/
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;
private createComboboxOptionsFromQuery;
private handleInput;
/**
* Checks if the current value is available in the options list.
* This is used to determine if the value is valid when the combobox is restricted.
*
* @returns `true` if the current value is available in the options list,
* otherwise `false`.
*/
private isValidValue;
private getOptionFromValue;
/**
* Resets the value to the last valid value or to an empty string.
*/
private resetToLastValidValue;
private handleChange;
private getSlottedOptions;
private getSlottedOptGroups;
private cacheSlottedOptionsAndOptgroups;
private updateSelectedOptionFromValue;
handleDefaultSlotChange(): void;
render(): import("lit").TemplateResult<1>;
}