@aquera/nile-elements 0.1.64-beta-1.1 → 0.1.64

package/dist/src/nile-virtual-select/nile-virtual-select.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Copyright Aquera Inc 2025
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import '../nile-icon';
+import '../nile-popup/nile-popup';
+import '../nile-tag/nile-tag';
+import '../nile-checkbox/nile-checkbox';
+import NileElement from '../internal/nile-element';
+import type { CSSResultGroup, TemplateResult } from 'lit';
+import type { NileFormControl } from '../internal/nile-element';
+import type NilePopup from '../nile-popup/nile-popup';
+import type { VirtualOption, RenderItemConfig } from './types.js';
+/**
+ * Nile Virtual Select component.
+ *
+ * @tag nile-virtual-select
+ *
+ */
+/**
+ * @summary Virtual select component for handling large datasets with virtual scrolling.
+ * @status stable
+ * @since 2.0
+ *
+ * @dependency nile-icon
+ * @dependency nile-popup
+ * @dependency nile-tag
+ * @dependency nile-checkbox
+ *
+ * @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 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.
+ * @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
+ *
+ * @event nile-change - Emitted when the control's value changes.
+ * @event nile-clear - Emitted when the control's value is cleared.
+ * @event nile-input - Emitted when the control receives input.
+ * @event nile-focus - Emitted when the control gains focus.
+ * @event nile-blur - Emitted when the control loses focus.
+ * @event nile-show - Emitted when the select's menu opens.
+ * @event nile-after-show - Emitted after the select's menu opens and all animations are complete.
+ * @event nile-hide - Emitted when the select's menu closes.
+ * @event nile-after-hide - Emitted after the select's menu closes and all animations are complete.
+ * @event nile-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, combobox, clear icon, and expand button.
+ * @csspart prefix - The container that wraps the prefix 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 `multiple` is used.
+ * @csspart tag - The individual tags that represent each multiselect option.
+ * @csspart clear-button - The clear button.
+ * @csspart expand-icon - The container that wraps the expand icon.
+ * @csspart footer - The footer container with show selected and clear all options.
+ */
+export declare class NileVirtualSelect extends NileElement implements NileFormControl {
+    static styles: CSSResultGroup;
+    private readonly formControlController;
+    private readonly hasSlotController;
+    popup: NilePopup;
+    displayInput: HTMLInputElement;
+    valueInput: HTMLInputElement;
+    virtualizedContainer: HTMLElement;
+    private hasFocus;
+    displayLabel: string;
+    selectedOptions: VirtualOption[];
+    oldValue: string | string[];
+    /** The name of the select, submitted as a name/value pair with form data. */
+    name: string;
+    /** Array of all option items for virtual scrolling */
+    data: any;
+    /** Original unfiltered option items for search functionality */
+    private originalOptionItems;
+    /**
+     * The current value of the select. When `multiple` is enabled, the value will be an array of selected values.
+     */
+    value: string | string[];
+    /** The default value of the form control. Primarily used for resetting the form control. */
+    defaultValue: string | string[];
+    /** The select's size. */
+    size: 'small' | 'medium' | 'large';
+    /** Placeholder text to show as a hint when the select is empty. */
+    placeholder: string;
+    /** Current search value */
+    searchValue: string;
+    /** Enable search functionality */
+    searchEnabled: boolean;
+    /** Search input placeholder */
+    internalSearchPlaceHolder: string;
+    /** Disable local search filtering */
+    disableLocalSearch: boolean;
+    /** Show loading state */
+    optionsLoading: boolean;
+    /** Allows more than one option to be selected. */
+    multiple: boolean;
+    /** Help text */
+    helpText: string;
+    /** Error message */
+    errorMessage: string;
+    /** Sets the input to a warning state */
+    warning: boolean;
+    /** Sets the input to an error state */
+    error: boolean;
+    /** Sets the input to a success state */
+    success: boolean;
+    /** Disables the select control. */
+    disabled: boolean;
+    /** Adds a clear button when the select is not empty. */
+    clearable: boolean;
+    /** 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;
+    /** Draws a filled select. */
+    filled: boolean;
+    /** Draws a pill-style select with rounded edges. */
+    pill: 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';
+    /**
+     * 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;
+    /** Show no results message */
+    showNoResults: boolean;
+    /** No results message */
+    noResultsMessage: string;
+    /** Show selected options only */
+    showSelected: boolean;
+    /** Enhanced configuration for rendering items with support for display text, value, and search text */
+    renderItemConfig?: RenderItemConfig;
+    /** Block value change events */
+    blockValueChange: boolean;
+    /** Disable width synchronization */
+    noWidthSync: 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;
+    oldMaxOptionsVisible: number;
+    /** Gets the validity state object */
+    get validity(): ValidityState;
+    /** Gets the validation message */
+    get validationMessage(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private initializeComponent;
+    /**
+     * Get display text for an item using renderItemConfig
+     */
+    private getDisplayText;
+    /**
+     * Get value for an item using renderItemConfig or fallback to item.value
+     */
+    private getItemValue;
+    /**
+     * Get search text for an item using renderItemConfig or fallback to display text
+     */
+    private getSearchText;
+    private setupEventListeners;
+    private addOpenListeners;
+    private removeOpenListeners;
+    private handleFocus;
+    private handleBlur;
+    private handleDocumentFocusIn;
+    private handleDocumentKeyDown;
+    private shouldIgnoreKeyPress;
+    private isEscapeKey;
+    private handleEscapeKey;
+    private isEnterOrSpaceKey;
+    private handleEnterOrSpaceKey;
+    private handleDocumentMouseDown;
+    private handleFooterClick;
+    private toggleShowSelected;
+    private unSelectAll;
+    private handleLabelClick;
+    private handleComboboxMouseDown;
+    private shouldIgnoreComboboxClick;
+    private handleComboboxKeyDown;
+    private handleClearClick;
+    private clearSelection;
+    private handleClearMouseDown;
+    private handleOptionClick;
+    private shouldBlockValueChange;
+    private handleOptionSelection;
+    private setSelectedOptions;
+    private toggleOptionSelection;
+    private handleTagRemove;
+    private removeTagFromSelection;
+    private emitTagRemovalEvent;
+    private selectionChanged;
+    handleSearchFocus(): void;
+    handleSearchBlur(): void;
+    handleSearchChange(e: any): void;
+    filterVirtualOptions(searchValue: string): void;
+    private handleInvalid;
+    handleDisabledChange(): void;
+    handleValueChange(): void;
+    handleDataChange(): void;
+    handleRenderItemConfigChange(): void;
+    handleOptionsLoadingChange(): void;
+    handleOpenChange(): Promise<void>;
+    private handleOpen;
+    private handleClose;
+    private initializeOriginalItems;
+    show(): Promise<unknown>;
+    hide(): Promise<unknown>;
+    checkValidity(): boolean;
+    getForm(): HTMLFormElement | null;
+    reportValidity(): boolean;
+    setCustomValidity(message: string): void;
+    focus(options?: FocusOptions): void;
+    blur(): void;
+    onInputChange(event: Event): void;
+    render(): TemplateResult;
+    private renderLabel;
+    private renderFormControlInput;
+    private renderPopup;
+    private renderCustomSelect;
+    private renderCombobox;
+    private renderPrefix;
+    private renderDisplayInput;
+    private renderTags;
+    private renderValueInput;
+    private renderClearButton;
+    private renderSuffix;
+    private renderExpandIcon;
+    private renderListbox;
+    private renderSearch;
+    private renderLoader;
+    private renderFooter;
+    private renderHelpText;
+    getVirtualizedContent(): TemplateResult;
+    nileInput(value: any): void;
+    nileChange(value: any): void;
+    private updateValidity;
+    private calculateWidthOfSelectTagsDiv;
+    private calculateTotalWidthOfTags;
+    private resetScrollPosition;
+}
+export default NileVirtualSelect;
+declare global {
+    interface HTMLElementTagNameMap {
+        'nile-virtual-select': NileVirtualSelect;
+    }
+}