@synergy-design-system/components/dist/components/combobox/combobox.component.d.ts

import type { CSSResultGroup, PropertyValues, TemplateResult } 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 SynTag from '../tag/tag.component.js';
import { type OptionRenderer } from './option-renderer.js';
/**
 * @summary A combobox component that combines the functionality of a text input with a dropdown listbox,
 * allowing users to either select from predefined options or enter custom values (when not restricted).
 *
 * @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-combobox--docs
 * @status stable
 * @since 2.8.0
 *
 * @dependency syn-icon
 * @dependency syn-popup
 * @dependency syn-tag
 *
 * @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 that 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.
 * @csspart tags - The container that houses option tags when `multiple` is used.
 * @csspart tag - The individual tags that represent each selected option in `multiple`.
 * @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.
 *
 * @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;
        'syn-tag': typeof SynTag;
    };
    private readonly formControlController;
    private readonly hasSlotController;
    private readonly localize;
    private closeWatcher;
    /**
     * Cache of the last syn-options that were selected by user interaction (click or keyboard navigation).
     * Used to track user selections and maintain selection state during value changes.
     */
    private lastOptions;
    private isInitialized;
    /**
     * Flag to prevent infinite loops when the option renderer programmatically updates options.
     * Set to true during option rendering to ignore slot change events triggered by our own updates.
     */
    private isOptionRendererTriggered;
    private resizeObserver;
    private mutationObserver;
    popup: SynPopup;
    combobox: HTMLSlotElement;
    displayInput: HTMLInputElement;
    valueInput: HTMLInputElement;
    listbox: HTMLSlotElement;
    private defaultSlot;
    tagContainer: HTMLDivElement;
    private hasFocus;
    private isUserInput;
    displayLabel: string;
    selectedOptions: SynOption[];
    numberFilteredOptions: number;
    cachedOptions: SynOption[];
    private valueHasChanged;
    private hideOptions;
    /** The name of the combobox, 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 combobox, submitted as a name/value pair with form data. When `multiple` is enabled, the
     * value attribute will be a list of values  separated by the delimiter, based on the options selected, and the value property will
     * be an array. **For this reason, values must not contain the delimiter character.**
     */
    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 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;
    /** Sets the combobox to a readonly state. */
    readonly: 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;
    /** The combobox's label. If you need to display HTML, use the `label` slot instead. */
    label: string;
    /** The maximum length of input that will be considered valid. */
    maxlength: number;
    /**
     * 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.
     * This will always be true, if `multiple` is active.
     */
    restricted: boolean;
    /**
     * Allows more than one option to be selected.
     * If `multiple` is set, the combobox will always be `restricted` to the available options
     * */
    multiple: 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;
    /**
     * 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(s).
     * @example <syn-combobox delimiter="~" value="option-1~option-2"></syn-combobox>
     */
    delimiter: string;
    /**
     * 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;
    /**
     * A function that customizes the tags to be rendered when `multiple` is 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 calculateTagMaxWidth;
    private enableResizeObserver;
    connectedCallback(): void;
    disconnectedCallback(): void;
    firstUpdated(): void;
    protected updated(changedProperties: PropertyValues<this>): void;
    protected willUpdate(changedProperties: PropertyValues): void;
    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
    protected get tags(): TemplateResult<1>[];
    private addOpenListeners;
    private removeOpenListeners;
    private handleFocus;
    private handleBlur;
    private handleDocumentFocusIn;
    private handleDocumentKeyDown;
    private handleDocumentMouseDown;
    private handleFormControlClick;
    private handleLabelClick;
    private handleTagRemove;
    private handleComboboxMouseDown;
    private handleComboboxKeyDown;
    private handleClearClick;
    private clearInputField;
    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 toggleOptionSelection;
    private setSelectedOptions;
    private getAllFilteredOptions;
    private getCurrentOption;
    private setCurrentOption;
    /**
     * Updates the component state after selection changes.
     *
     * This method synchronizes:
     * 1. The selectedOptions cache with currently selected options
     * 2. The component's value property (string or array)
     * 3. The display label shown in the input
     * 4. Form validation state
     *
     * **Validation Logic:**
     * - In restricted mode, invalid values trigger a reset to last valid state
     * - Multiple mode requires all values to correspond to existing options
     * - Single mode allows free text input when not restricted
     */
    private selectionChanged;
    private handleInvalid;
    handlePropertiesChange(): void;
    handleDisplayInputValueChange(): void;
    handleDisabledChange(): void;
    handleDelimiterChange(): 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;
    /**
     * Updates the visibility and rendering of options based on the current query string.
     *
     * This method performs several critical tasks:
     * 1. **Option Filtering**: Uses the `filter` function to determine which options should be visible
     * 2. **Custom Rendering**: Applies the `getOption` function to customize option appearance
     * 3. **Optgroup Management**: Shows/hides optgroups based on their visible children
     * 4. **Counts visible options**: Tracks the number of visible options for UI logic
     *
     * **Performance Considerations:**
     * - Uses cached options to avoid repeated DOM queries
     * - Prevents infinite loops during option updates with `isOptionRendererTriggered`
     *
     * @param queryString - The current user input to filter and highlight options with
     */
    private createComboboxOptionsFromQuery;
    private handleInput;
    /**
     * Checks if the value is available in the options list.
     * This is used to determine if the value is valid when the combobox is restricted.
     * @param value - The value to check for validity.
     * @returns `true` if the current value is available in the options list,
     * otherwise `false`.
     */
    private isValidValue;
    private getOptionsFromValue;
    /**
     * 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;
    /**
     * Synchronizes the internal component state with changes to slotted options.
     *
     * This method is automatically triggered by:
     * - MutationObserver when option 'value' attributes change
     * - Initial component setup during connectedCallback (after timeout)
     * - Default slot changes (via handleDefaultSlotChange)
     * - Custom element registration completion for syn-option (deferred execution)
     *
     * The synchronization process:
     * 1. Waits for syn-option custom elements to be registered before processing
     * 2. Updates delimiter settings on all slotted options
     * 3. Refreshes the internal cache of options and optgroups
     * 4. Synchronizes selected options based on current component value
     * 5. Auto-opens listbox if component has focus, has value, and is currently closed
     *
     * This ensures the component's internal state stays consistent with the slotted
     * DOM content after options are added, removed, or their values change.
     *
     */
    private handleSlotContentChange;
    handleDefaultSlotChange(): void;
    render(): TemplateResult<1>;
}