@keenthemes/ktui 1.1.6 → 1.2.0

package/lib/cjs/components/select/select.d.ts

@@ -0,0 +1,427 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+import KTComponent from '../component';
+import { KTSelectConfigInterface } from './config';
+export declare class KTSelect extends KTComponent {
+    protected readonly _name: string;
+    protected readonly _dataOptionPrefix: string;
+    protected readonly _config: KTSelectConfigInterface;
+    protected _defaultConfig: KTSelectConfigInterface;
+    private static globalConfig;
+    private static openDropdowns;
+    private _wrapperElement;
+    private _displayElement;
+    private _dropdownContentElement;
+    private _searchInputElement;
+    private _options;
+    private _optionsContainer;
+    private _dropdownIsOpen;
+    private _state;
+    private _searchModule;
+    private _remoteModule;
+    private _comboboxModule;
+    private _tagsModule;
+    private _dropdownModule;
+    private _loadMoreIndicator;
+    private _selectAllButton;
+    private _selectAllButtonToggle;
+    private _focusManager;
+    private _eventManager;
+    private _typeToSearchBuffer;
+    private _mutationObserver;
+    private _preSelectedValues;
+    /**
+     * Constructor: Initializes the select component
+     */
+    constructor(element: HTMLElement, config?: KTSelectConfigInterface);
+    /**
+     * Set global select configuration options.
+     * This allows setting default configuration that will be applied to all new KTSelect instances.
+     * @param options Partial select config to merge with global config.
+     * @example
+     * KTSelect.config({
+     *   enableSearch: true,
+     *   searchPlaceholder: 'Type to search...',
+     *   dropdownZindex: 9999,
+     *   height: 300
+     * });
+     */
+    static config(options: Partial<KTSelectConfigInterface>): void;
+    /**
+     * Override _buildConfig to include static globalConfig in the merge chain
+     */
+    protected _buildConfig(config?: object): void;
+    /**
+     * Override _dispatchEvent to also dispatch on document for global listeners (jQuery compatibility)
+     */
+    protected _dispatchEvent(eventType: string, payload?: object): void;
+    /**
+     * Initialize remote data fetching
+     */
+    private _initializeRemoteData;
+    /**
+     * Clear existing options from the select element
+     */
+    private _clearExistingOptions;
+    /**
+     * Unified method to render options in dropdown - eliminates code duplication
+     */
+    private _renderOptionsInDropdown;
+    /**
+     * Update dropdown with new options from the original select element
+     */
+    private _updateDropdownWithNewOptions;
+    /**
+     * Complete the setup for remote data after HTML structure is created
+     */
+    private _completeRemoteSetup;
+    /**
+     * Helper to show a dropdown message (error, loading, noResults)
+     */
+    private _showDropdownMessage;
+    /**
+     * Render loading state in dropdown
+     */
+    private _renderLoadingState;
+    /**
+     * Render error state
+     * @param message Error message
+     */
+    private _renderErrorState;
+    /**
+     * Add "Load More" button for pagination
+     */
+    private _addLoadMoreButton;
+    /**
+     * Handle load more button click
+     */
+    private _handleLoadMore;
+    /**
+     * Update options in the dropdown
+     * @param newItems New items to add to the dropdown
+     */
+    private _updateOptionsInDropdown;
+    /**
+     * ========================================================================
+     * INITIALIZATION METHODS
+     * ========================================================================
+     */
+    /**
+     * Set up the component after everything is initialized
+     */
+    private _setupComponent;
+    /**
+     * Creates the HTML structure for the select component
+     */
+    private _createHtmlStructure;
+    /**
+     * Setup all element references after DOM is created
+     */
+    private _setupElementReferences;
+    /**
+     * Attach all event listeners to elements
+     */
+    private _attachEventListeners;
+    /**
+     * Initialize search module if search is enabled
+     */
+    private _initializeSearchModule;
+    /**
+     * Apply ARIA attributes and update display
+     */
+    private _updateDisplayAndAriaAttributes;
+    /**
+     * Apply initial disabled state if configured
+     */
+    private _applyInitialDisabledState;
+    /**
+     * Generate options HTML from data items
+     */
+    private _generateOptionsHtml;
+    /**
+     * Extract nested property value from object using dot notation
+     */
+    private _getValueByKey;
+    /**
+     * Pre-select options that have the selected attribute
+     */
+    private _preSelectOptions;
+    /**
+     * ========================================================================
+     * DROPDOWN MANAGEMENT
+     * ========================================================================
+     */
+    /**
+     * Open the dropdown
+     */
+    openDropdown(): void;
+    /**
+     * Close the dropdown
+     */
+    closeDropdown(): void;
+    /**
+     * Update dropdown position
+     */
+    updateDropdownPosition(): void;
+    /**
+     * Focus on the first selected option if any exists in the dropdown
+     */
+    private _focusSelectedOption;
+    /**
+     * ========================================================================
+     * SELECTION MANAGEMENT
+     * ========================================================================
+     */
+    /**
+     * Select an option by value
+     */
+    private _selectOption;
+    /**
+     * Sync native select value attribute for FormData support
+     */
+    private _syncNativeSelectValue;
+    /**
+     * Update selected option display value
+     */
+    updateSelectedOptionDisplay(): void;
+    /**
+     * Check if an option was originally disabled in the HTML
+     */
+    private _isOptionOriginallyDisabled;
+    /**
+     * Update CSS classes for selected options
+     */
+    private _updateSelectedOptionClass;
+    /**
+     * Clear all selected options
+     */
+    clearSelection(): void;
+    /**
+     * Deselect a specific option by value
+     * @param value The value of the option to deselect
+     * @public
+     */
+    deselectOption(value: string): void;
+    /**
+     * Set selected options programmatically
+     */
+    setSelectedOptions(options: HTMLOptionElement[]): void;
+    /**
+     * Select the currently focused option
+     */
+    selectFocusedOption(): void;
+    /**
+     * ========================================================================
+     * EVENT HANDLERS
+     * ========================================================================
+     */
+    /**
+     * Handle click within the dropdown
+     */
+    private _handleDropdownOptionClick;
+    /**
+     * Handle clicking on an option in the dropdown
+     */
+    private _handleOptionClick;
+    /**
+     * Handle document click for closing dropdown
+     */
+    private _handleDocumentClick;
+    /**
+     * ========================================================================
+     * ACCESSIBILITY METHODS
+     * ========================================================================
+     */
+    /**
+     * Set ARIA attributes for accessibility
+     */
+    private _setAriaAttributes;
+    /**
+     * ========================================================================
+     * PUBLIC API
+     * ========================================================================
+     */
+    /**
+     * Get the search input element
+     */
+    getSearchInput(): HTMLInputElement;
+    /**
+     * Get selected options
+     */
+    getSelectedOptions(): string[];
+    /**
+     * Get configuration
+     */
+    getConfig(): KTSelectConfigInterface;
+    /**
+     * Get option elements
+     */
+    getOptionsElement(): NodeListOf<HTMLElement>;
+    /**
+     * Get dropdown element
+     */
+    getDropdownElement(): HTMLElement;
+    /**
+     * Get value display element
+     */
+    getValueDisplayElement(): HTMLElement;
+    /**
+     * Get wrapper element
+     */
+    getWrapperElement(): HTMLElement;
+    /**
+     * Show all options in the dropdown
+     */
+    showAllOptions(): void;
+    /**
+     * Toggle multi-select functionality
+     */
+    enableMultiSelect(): void;
+    /**
+     * Disable multi-select functionality
+     */
+    disableMultiSelect(): void;
+    /**
+     * Toggle the selection of an option
+     */
+    toggleSelection(value: string): void;
+    /**
+     * Clean up all resources when the component is destroyed
+     * This overrides the parent dispose method
+     */
+    dispose(): void;
+    /**
+     * ========================================================================
+     * DYNAMIC CONTROL METHODS
+     * ========================================================================
+     */
+    /**
+     * Programmatically enable the select component
+     * @public
+     */
+    enable(): void;
+    /**
+     * Programmatically disable the select component
+     * @public
+     */
+    disable(): void;
+    /**
+     * Update the dropdown to sync with native select element changes
+     * For remote selects, refetches data from the server and preserves selections
+     * Optionally accepts new options to replace existing ones (static selects only)
+     *
+     * @param newOptions Optional array of new options [{value, text}, ...] (static selects only)
+     * @public
+     * @remarks
+     * - For static selects: rebuilds dropdown from native select or new options
+     * - For remote selects: fetches fresh data, preserves matching selections
+     * - Selections are preserved if their values exist in new remote data
+     * - Selections are cleared if their values don't exist in new data
+     * @fires updated - After update completes successfully
+     * @fires updateError - If remote data fetch fails
+     */
+    update(newOptions?: Array<{
+        value: string;
+        text: string;
+    }>): void;
+    /**
+     * Reload remote data and rebuild the dropdown
+     * Only works with remote data enabled
+     * @returns Promise that resolves when reload completes
+     * @public
+     */
+    reload(): Promise<void>;
+    /**
+     * Refresh the visual display and state without rebuilding options
+     * For remote selects, refetches data from the server and preserves selections
+     * that exist in the newly fetched data
+     *
+     * @public
+     * @remarks
+     * - For static selects: syncs visual state with native select
+     * - For remote selects: fetches fresh data, preserves matching selections
+     * - Selections are preserved if their values exist in new remote data
+     * - Selections are cleared if their values don't exist in new data
+     * @fires refreshed - After refresh completes successfully
+     * @fires refreshError - If remote data fetch fails
+     */
+    refresh(): void;
+    /**
+     * ========================================================================
+     * STATIC METHODS
+     * ========================================================================
+     */
+    /**
+     * Create instances of KTSelect for all matching elements
+     */
+    static createInstances(): void;
+    /**
+     * Initialize all KTSelect instances
+     */
+    static init(): void;
+    /**
+     * Get an existing KTSelect instance from an element
+     */
+    static getInstance(element: HTMLElement): KTSelect | null;
+    /**
+     * Get an existing KTSelect instance or create a new one
+     */
+    static getOrCreateInstance(element: HTMLElement, config?: KTSelectConfigInterface): KTSelect;
+    /**
+     * Handle remote search
+     * @param event Input event
+     */
+    private _handleRemoteSearch;
+    private _searchDebounceTimeout;
+    /**
+     * Render loading state for search
+     */
+    private _renderSearchLoadingState;
+    private _originalOptionsHtml;
+    /**
+     * Render error state for search
+     * @param message Error message
+     */
+    private _renderSearchErrorState;
+    /**
+     * Restore original options when search is cleared
+     */
+    private _restoreOriginalOptions;
+    /**
+     * Update search results in the dropdown
+     * @param items Search result items
+     */
+    private _updateSearchResults;
+    /**
+     * Update original select element with search results
+     * @param items Search result items
+     */
+    private _updateOriginalSelectWithSearchResults;
+    /**
+     * Check if dropdown is open
+     */
+    isDropdownOpen(): boolean;
+    getSelectedOptionsText(): string;
+    /**
+     * Check if an option is disabled (either in dropdown or original select)
+     */
+    private _isOptionDisabled;
+    /**
+     * Centralized keyboard event handler for all select modes
+     */
+    private _handleKeyboardEvent;
+    renderDisplayTemplateForSelected(selectedValues: string[]): string;
+    getDisplayElement(): HTMLElement;
+    private _observeNativeSelect;
+    private _rebuildOptionsFromNative;
+    private _syncSelectionFromNative;
+    private _handleSelectAllClick;
+    updateSelectAllButtonState(): void;
+    /**
+     * Destroy the component and clean up resources
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=select.d.ts.map

package/lib/cjs/components/select/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../../src/components/select/select.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,WAAW,MAAM,cAAc,CAAC;AACvC,OAAO,EACN,uBAAuB,EAGvB,MAAM,UAAU,CAAC;AAelB,qBAAa,QAAS,SAAQ,WAAW;IAExC,mBAA4B,KAAK,EAAE,MAAM,CAAY;IACrD,mBAA4B,iBAAiB,EAAE,MAAM,CAAS;IAC9D,mBAA4B,OAAO,EAAE,uBAAuB,CAAC;IAC7D,UAAmB,cAAc,EAAE,uBAAuB,CAAC;IAG3D,OAAO,CAAC,MAAM,CAAC,YAAY,CAAwC;IAGnE,OAAO,CAAC,MAAM,CAAC,aAAa,CAA4B;IAGxD,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,uBAAuB,CAAc;IAC7C,OAAO,CAAC,mBAAmB,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAA0B;IAG1C,OAAO,CAAC,iBAAiB,CAA4B;IAGrD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,sBAAsB,CAAkC;IAChE,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,mBAAmB,CAAgD;IAC3E,OAAO,CAAC,iBAAiB,CAAiC;IAC1D,OAAO,CAAC,kBAAkB,CAAgB;IAE1C;;OAEG;gBACS,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,uBAAuB;IAmClE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,IAAI;IAI9D;;OAEG;cACgB,YAAY,CAAC,MAAM,GAAE,MAAW,GAAG,IAAI;IAgB1D;;OAEG;cACgB,cAAc,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAa,GACpB,IAAI;IAmCP;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiD7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA+DhC;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAQrC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA6G5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAwDvB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAmChC;;;;OAIG;IAEH;;OAEG;IACH,OAAO,CAAC,eAAe;IAmEvB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAyF5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAoE/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiC7B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAmB/B;;OAEG;IACH,OAAO,CAAC,+BAA+B;IAKvC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAQlC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmD5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;OAIG;IAEH;;OAEG;IACI,YAAY;IA8EnB;;OAEG;IACI,aAAa;IA8CpB;;OAEG;IACI,sBAAsB;IAM7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;;;OAIG;IAEH;;OAEG;IACH,OAAO,CAAC,aAAa;IAsDrB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;OAEG;IACI,2BAA2B;IA0DlC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAOnC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAyClC;;OAEG;IACI,cAAc;IAuBrB;;;;OAIG;IACI,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAsD1C;;OAEG;IACI,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE;IAOtD;;OAEG;IACI,mBAAmB;IA0B1B;;;;OAIG;IAEH;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAWlC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;;;OAIG;IAEH;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;OAIG;IAEH;;OAEG;IACI,cAAc,IAAI,gBAAgB;IAIzC;;OAEG;IACI,kBAAkB;IAIzB;;OAEG;IACI,SAAS,IAAI,uBAAuB;IAI3C;;OAEG;IACI,iBAAiB,IAAI,UAAU,CAAC,WAAW,CAAC;IAInD;;OAEG;IACI,kBAAkB;IAIzB;;OAEG;IACI,sBAAsB;IAI7B;;OAEG;IACI,iBAAiB,IAAI,WAAW;IAIvC;;OAEG;IACI,cAAc;IA2CrB;;OAEG;IACI,iBAAiB;IAIxB;;OAEG;IACI,kBAAkB;IAIzB;;OAEG;IACI,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAgF3C;;;OAGG;IACa,OAAO,IAAI,IAAI;IAoC/B;;;;OAIG;IAEH;;;OAGG;IACI,MAAM,IAAI,IAAI;IAsBrB;;;OAGG;IACI,OAAO,IAAI,IAAI;IA2BtB;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IA0ExE;;;;;OAKG;IACI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA4E9B;;;;;;;;;;;;;OAaG;IACI,OAAO,IAAI,IAAI;IAoEtB;;;;OAIG;IAEH;;OAEG;WACW,eAAe,IAAI,IAAI;IAarC;;OAEG;WACW,IAAI,IAAI,IAAI;IAI1B;;OAEG;WACW,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI;IAchE;;OAEG;WACW,mBAAmB,CAChC,OAAO,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,uBAAuB,GAC9B,QAAQ;IAIX;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA6D3B,OAAO,CAAC,sBAAsB,CAAuB;IAErD;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAajC,OAAO,CAAC,oBAAoB,CAAuB;IAEnD;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAwB/B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA6B5B;;;OAGG;IACH,OAAO,CAAC,sCAAsC;IAqB9C;;OAEG;IACI,cAAc,IAAI,OAAO;IAIzB,sBAAsB,IAAI,MAAM;IAcvC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4IrB,gCAAgC,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM;IAqClE,iBAAiB,IAAI,WAAW;IAIvC,OAAO,CAAC,oBAAoB;IAqC5B,OAAO,CAAC,yBAAyB;IAgCjC,OAAO,CAAC,wBAAwB;IAahC,OAAO,CAAC,qBAAqB;IAkCtB,0BAA0B,IAAI,IAAI;IA8BzC;;OAEG;IACI,OAAO,IAAI,IAAI;CAYtB"}

package/lib/cjs/components/select/select.js

@@ -2272,4 +2272,7 @@ var KTSelect = /** @class */ (function (_super) {
     return KTSelect;
 }(component_1.default));
 exports.KTSelect = KTSelect;
+if (typeof window !== 'undefined') {
+    window.KTSelect = KTSelect;
+}
 //# sourceMappingURL=select.js.map