atomicuilibrary 0.0.1

package/dist/collection/components/dropdown/dropdown.js

@@ -0,0 +1,2033 @@
+import { h } from "@stencil/core";
+import { ariaLive } from "../../utils/aria-live";
+import { calculateUniversalPlacement } from "../../utils/dom";
+export class Dropdown {
+    hostElement;
+    /**
+     * Options as JSON string or DropdownOption array
+     */
+    options = [];
+    /**
+     * Placeholder text
+     */
+    placeholder = 'Select an option';
+    /**
+     * Enable multi-select mode
+     */
+    multiSelect = false;
+    /**
+     * Enable cascading/hierarchical selection
+     */
+    cascading = false;
+    /**
+     * Selected value(s) - string for single, comma-separated for multi
+     */
+    value = '';
+    /**
+     * Disabled state
+     */
+    disabled = false;
+    /**
+     * Show search/filter input
+     */
+    searchable = false;
+    /**
+     * Maximum height of dropdown (in pixels)
+     */
+    maxHeight = 300;
+    /**
+     * Size variant
+     */
+    size = 'md';
+    /**
+     * Appearance: default dropdown or button-like (no arrow)
+     */
+    appearance = 'dropdown';
+    /**
+     * Aesthetic variant
+     */
+    variant = 'default';
+    /**
+     * Use chips for multi-select display
+     */
+    chipView = false;
+    /**
+     * Controls visibility of the arrow icon. If false, no arrow is shown.
+     * Defaults to true for dropdown appearance; false when appearance is 'button'.
+     */
+    showArrow;
+    /**
+     * If true, dropdown positioning ignores transformed/positioned parent offsets.
+     * Use this when the menu is portaled and should stay anchored to viewport coordinates.
+     */
+    ignoreParentPosition = true;
+    /**
+     * Show clear (✕) button when a value is selected.
+     * - When not set (default): automatically shown for multi-select, hidden for single-select.
+     * - Set to `true`  : always show the clear button (both single & multi).
+     * - Set to `false` : always hide the clear button (both single & multi).
+     */
+    clearable;
+    /**
+     * If true, the dropdown will take up the full width of its container.
+     */
+    fullWidth = false;
+    /**
+     * If true, the dropdown width fits its longest option (max-content).
+     */
+    fitContent = false;
+    /**
+     * Optional width for the dropdown options panel.
+     * Accepts a number (pixels) or any valid CSS width value such as `320px`, `24rem`, or `min(28rem, 90vw)`.
+     * By default, the menu matches the trigger width.
+     */
+    menuWidth;
+    /**
+     * Loading state
+     */
+    loading = false;
+    /**
+     * Validation state
+     */
+    invalid = false;
+    /**
+     * Helper text / validation message
+     */
+    helperText;
+    /**
+     * Error message to show when invalid
+     */
+    errorMessage;
+    /**
+     * Placeholder for the search input
+     */
+    searchPlaceholder = 'Search...';
+    /**
+     * Default icon library for option icons (e.g. 'lucide', 'ionicons')
+     */
+    iconLibrary = 'ionicons';
+    /**
+     * If true, show the full hierarchy path in selected value (for cascading)
+     */
+    showPath = false;
+    /** Use high-fidelity animation (Framer-like physics) */
+    highFidelity = true;
+    /** RTL support */
+    rtl = false;
+    /**
+     * Shape variant (inherits from design system or parent)
+     */
+    shape = 'default';
+    /**
+     * If true, shows a checkmark (tick) next to the selected item in single-select mode.
+     */
+    showSelectedMarker = true;
+    /**
+     * Custom icon for the selection marker
+     */
+    selectedMarkerIcon = 'check';
+    /**
+     * Icon library for the selection marker icon
+     */
+    selectedMarkerLibrary = 'lucide';
+    /**
+     * Optional label text shown after the checkmark on the selected item.
+     */
+    selectedMarkerLabel = '';
+    /**
+     * Color for the selection marker icon. Defaults to the selected state color token.
+     */
+    selectedMarkerColor = '';
+    isOpen = false;
+    parsedOptions = [];
+    selectedValues = new Set();
+    searchQuery = '';
+    expandedNodes = new Set();
+    dropdownPosition = 'bottom';
+    menuLeft = 0;
+    menuTop = 0;
+    computedMenuWidth = 0;
+    menuMaxHeight = 0;
+    highlightedIndex = -1;
+    nestedPath = [];
+    optionsRef = [];
+    searchInputRef;
+    searchDebounce;
+    menuElement;
+    rafId = null;
+    isPortaled = false;
+    handleDocumentClick = (event) => {
+        if (!this.isOpen)
+            return;
+        const path = event.composedPath();
+        const isInsideHost = path.some(node => node === this.hostElement);
+        const isInsideMenu = this.menuElement && path.some(node => node === this.menuElement || (node instanceof Node && this.menuElement.contains(node)));
+        if (!isInsideHost && !isInsideMenu) {
+            this.closeDropdown();
+        }
+    };
+    /**
+     * If true, all nodes in a cascading dropdown will be expanded by default.
+     */
+    expandAll = false;
+    /**
+     * If true, shows a skeleton loading state for the trigger
+     */
+    skeleton = false;
+    /**
+     * If true, shows a "Select All" option in multi-select mode
+     */
+    showSelectAll = false;
+    /**
+     * Label for the Select All option
+     */
+    selectAllLabel = 'Select All';
+    /**
+     * Custom text color for the dropdown display
+     */
+    textColor = '';
+    /**
+     * If true, enables virtual scrolling (renders only a subset of items for performance)
+     */
+    virtualScroll = false;
+    /**
+     * If true, search filtering is case-sensitive
+     */
+    caseSensitive = false;
+    /**
+     * Label text shown above the dropdown
+     */
+    label = '';
+    /**
+     * Emitted when value changes
+     */
+    valueChange;
+    /**
+     * Emitted when dropdown opens
+     */
+    dropdownOpen;
+    /**
+     * Emitted when dropdown closes
+     */
+    dropdownClose;
+    handleOptionsChange(newValue) {
+        this.parseOptions(newValue);
+        this.syncNestedPath();
+    }
+    handleValueChange(newValue) {
+        this.updateSelectedValues(newValue);
+        this.syncNestedPath();
+    }
+    handleSearchQueryChange() {
+        clearTimeout(this.searchDebounce);
+        this.searchDebounce = setTimeout(() => {
+            const count = this.getVisibleOptionCount();
+            ariaLive.announce(`${count} option${count !== 1 ? 's' : ''} found`);
+        }, 300);
+    }
+    componentWillLoad() {
+        this.parseOptions(this.options);
+        this.updateSelectedValues(this.value);
+        this.syncNestedPath();
+        if (this.expandAll && this.cascading) {
+            this.expandAllNodes(this.parsedOptions);
+        }
+    }
+    expandAllNodes(options) {
+        options.forEach(opt => {
+            if (opt.children) {
+                this.expandedNodes.add(opt.value.toString());
+                this.expandAllNodes(opt.children);
+            }
+        });
+        this.expandedNodes = new Set(this.expandedNodes);
+    }
+    /**
+     * Programmatically open the dropdown menu
+     */
+    async open() {
+        if (!this.isOpen) {
+            this.toggleDropdown();
+        }
+    }
+    componentDidUpdate() {
+        if (this.isOpen && this.menuElement) {
+            this.calculateDropdownPosition();
+        }
+    }
+    connectedCallback() {
+        this.handleViewportChange = this.handleViewportChange.bind(this);
+        window.addEventListener('scroll', this.handleViewportChange, true);
+        window.addEventListener('resize', this.handleViewportChange);
+        document.addEventListener('click', this.handleDocumentClick, true);
+        window.addEventListener('popstate', this.closeDropdown);
+        window.addEventListener('hashchange', this.closeDropdown);
+    }
+    disconnectedCallback() {
+        window.removeEventListener('scroll', this.handleViewportChange, true);
+        window.removeEventListener('resize', this.handleViewportChange);
+        document.removeEventListener('click', this.handleDocumentClick, true);
+        window.removeEventListener('popstate', this.closeDropdown);
+        window.removeEventListener('hashchange', this.closeDropdown);
+        this.cleanupPortal();
+    }
+    getOptionId(index) {
+        return `dropdown-option-${index}`;
+    }
+    handleKeyDown = (event) => {
+        if (this.disabled)
+            return;
+        if (!this.searchable && event.key.length === 1 && this.isOpen) {
+            const char = event.key.toLowerCase();
+            const flatOptions = this.getVisibleOptions();
+            const startIndex = this.highlightedIndex + 1;
+            const searchList = [...flatOptions.slice(startIndex), ...flatOptions.slice(0, startIndex)];
+            const matchIndex = searchList.findIndex(o => (o.label ?? '').toLowerCase().startsWith(char));
+            if (matchIndex !== -1) {
+                let trueIndex = startIndex + matchIndex;
+                if (trueIndex >= flatOptions.length)
+                    trueIndex -= flatOptions.length;
+                this.highlightedIndex = trueIndex;
+                this.scrollToHighlighted();
+                ariaLive.announce(flatOptions[trueIndex].label ?? '');
+            }
+            return;
+        }
+        switch (event.key) {
+            case 'Enter':
+            case ' ':
+                if (!this.isOpen) {
+                    event.preventDefault();
+                    this.toggleDropdown();
+                }
+                else if (this.highlightedIndex >= 0) {
+                    event.preventDefault();
+                    const flatOptions = this.getVisibleOptions();
+                    if (flatOptions[this.highlightedIndex]) {
+                        this.handleOptionClick(flatOptions[this.highlightedIndex], event);
+                    }
+                }
+                break;
+            case 'ArrowDown':
+                event.preventDefault();
+                if (!this.isOpen) {
+                    this.toggleDropdown();
+                }
+                else {
+                    const count = this.getVisibleOptionCount();
+                    this.highlightedIndex = Math.min(this.highlightedIndex + 1, count - 1);
+                    this.scrollToHighlighted();
+                }
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                if (this.isOpen) {
+                    this.highlightedIndex = Math.max(this.highlightedIndex - 1, 0);
+                    this.scrollToHighlighted();
+                }
+                break;
+            case 'Escape':
+                if (this.isOpen) {
+                    event.preventDefault();
+                    this.closeDropdown();
+                    this.hostElement.shadowRoot?.querySelector('.dropdown-trigger')?.focus();
+                }
+                break;
+            case 'Tab':
+                if (this.isOpen) {
+                    this.closeDropdown();
+                }
+                break;
+        }
+    };
+    getVisibleOptions() {
+        if (this.isNestedMenuVariant()) {
+            return this.getNestedMenuLevels(this.filterOptions(this.parsedOptions)).flat();
+        }
+        const flatOptions = [];
+        const flatten = (opts) => {
+            opts.forEach(o => {
+                flatOptions.push(o);
+                if (o.children && (this.expandedNodes.has(o.value?.toString() ?? '') || this.searchQuery)) {
+                    flatten(o.children);
+                }
+            });
+        };
+        if (this.cascading)
+            flatten(this.filterOptions(this.parsedOptions));
+        else {
+            const filtered = this.filterOptions(this.parsedOptions);
+            filtered.forEach(o => flatOptions.push(o));
+        }
+        return flatOptions;
+    }
+    getVisibleOptionCount() {
+        return this.getVisibleOptions().length;
+    }
+    scrollToHighlighted() {
+        const optionEl = this.optionsRef[this.highlightedIndex];
+        if (optionEl) {
+            optionEl.scrollIntoView({ block: 'nearest' });
+        }
+    }
+    isNestedMenuVariant() {
+        return this.variant === 'nested-menu' && this.cascading && !this.searchQuery;
+    }
+    findOptionPathByValue(options, targetValue, path = []) {
+        for (const option of options) {
+            const currentValue = option.value?.toString() ?? '';
+            const nextPath = currentValue ? [...path, currentValue] : [...path];
+            if (currentValue === targetValue) {
+                return nextPath;
+            }
+            if (option.children) {
+                const childPath = this.findOptionPathByValue(option.children, targetValue, nextPath);
+                if (childPath) {
+                    return childPath;
+                }
+            }
+        }
+        return null;
+    }
+    syncNestedPath() {
+        if (this.variant !== 'nested-menu' || !this.cascading) {
+            this.nestedPath = [];
+            return;
+        }
+        const selectedValue = Array.from(this.selectedValues)[0];
+        if (!selectedValue) {
+            this.nestedPath = [];
+            return;
+        }
+        this.nestedPath = this.findOptionPathByValue(this.parsedOptions, selectedValue) ?? [];
+    }
+    setNestedPath(level, value) {
+        const nextPath = this.nestedPath.slice(0, level);
+        nextPath[level] = value;
+        this.nestedPath = nextPath;
+    }
+    getNestedMenuLevels(options) {
+        const levels = [];
+        let currentOptions = options;
+        if (currentOptions.length > 0) {
+            levels.push(currentOptions);
+        }
+        for (let level = 0; level < this.nestedPath.length; level++) {
+            const activeValue = this.nestedPath[level];
+            const activeOption = currentOptions.find(option => (option.value?.toString() ?? '') === activeValue);
+            if (!activeOption?.children?.length) {
+                break;
+            }
+            currentOptions = activeOption.children;
+            levels.push(currentOptions);
+        }
+        return levels;
+    }
+    getNestedMenuEstimatedWidth() {
+        const perPanelWidth = this.size === 'sm' ? 190 : this.size === 'lg' ? 260 : 220;
+        const levelCount = Math.max(1, this.getNestedMenuLevels(this.filterOptions(this.parsedOptions)).length);
+        return perPanelWidth * levelCount;
+    }
+    parseOptions(options) {
+        let rawOptions = [];
+        if (typeof options === 'string' && options.length > 0) {
+            try {
+                rawOptions = JSON.parse(options);
+            }
+            catch (error) {
+                console.error('Invalid JSON for dropdown options:', error);
+                rawOptions = [];
+            }
+        }
+        else if (Array.isArray(options) && options.length > 0) {
+            rawOptions = options;
+        }
+        else {
+            // Fallback: Parse native <option> tags from children
+            const nativeOptions = Array.from(this.hostElement.querySelectorAll('option'));
+            if (nativeOptions.length > 0) {
+                rawOptions = nativeOptions.map(opt => ({
+                    label: opt.textContent || '',
+                    value: opt.value || opt.textContent || '',
+                    disabled: opt.disabled,
+                    ...(opt.dataset.icon ? { icon: opt.dataset.icon } : {}),
+                    ...(opt.dataset.subtitle ? { subtitle: opt.dataset.subtitle } : {}),
+                    ...(opt.dataset.description ? { description: opt.dataset.description } : {}),
+                    ...(opt.dataset.group ? { group: opt.dataset.group } : {}),
+                }));
+            }
+            else {
+                rawOptions = [];
+            }
+        }
+        // Transform DropdownGroup to flat list with 'group' property if detected
+        const transformed = [];
+        rawOptions.forEach(opt => {
+            if (opt.options && Array.isArray(opt.options)) {
+                // This is a group
+                opt.options.forEach((child) => {
+                    transformed.push({ ...child, group: opt.label });
+                });
+            }
+            else {
+                // This is a direct option
+                transformed.push(opt);
+            }
+        });
+        this.parsedOptions = transformed;
+    }
+    updateSelectedValues(valueString) {
+        if (!valueString) {
+            this.selectedValues = new Set();
+        }
+        else if (this.multiSelect) {
+            this.selectedValues = new Set(valueString.split(',').filter(v => v));
+        }
+        else {
+            this.selectedValues = new Set([valueString]);
+        }
+    }
+    toggleDropdown = () => {
+        if (this.disabled)
+            return;
+        // Only open if trigger is visible
+        const trigger = (this.hostElement.shadowRoot?.querySelector('.dropdown-trigger') || this.hostElement.querySelector('.dropdown-trigger'));
+        if (!trigger)
+            return;
+        const rect = trigger.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            return;
+        this.isOpen = !this.isOpen;
+        if (this.isOpen) {
+            this.dropdownOpen.emit();
+            this.highlightedIndex = -1;
+            if (this.variant === 'nested-menu' && this.cascading) {
+                this.syncNestedPath();
+            }
+            this.schedulePositionUpdate();
+            if (!this.multiSelect && this.selectedValues.size > 0) {
+                const visible = this.getVisibleOptions();
+                const idx = visible.findIndex(o => this.selectedValues.has(o.value?.toString() ?? ''));
+                if (idx !== -1)
+                    this.highlightedIndex = idx;
+            }
+            setTimeout(() => {
+                this.calculateDropdownPosition(); // Force recalculation after paint
+                if (this.searchable && this.searchInputRef) {
+                    this.searchInputRef.focus();
+                }
+            }, 50);
+        }
+        else {
+            this.closeDropdown();
+        }
+    };
+    /**
+     * Schedule position updates after the menu element renders.
+     * Since the trigger has a CSS transition (0.2s), we re-calculate for 250ms
+     * to ensure the menu stays perfectly aligned as the transition progresses.
+     */
+    schedulePositionUpdate() {
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+        }
+        const startTime = performance.now();
+        const update = (now) => {
+            if (!this.isOpen) {
+                this.rafId = null;
+                return;
+            }
+            this.calculateDropdownPosition();
+            // Continue updating during the transition period (250ms)
+            if (now - startTime < 250) {
+                this.rafId = requestAnimationFrame(update);
+            }
+            else {
+                this.rafId = null;
+            }
+        };
+        this.rafId = requestAnimationFrame(update);
+    }
+    cleanupPortal() {
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        if (this.isPortaled && this.menuElement && this.menuElement.parentElement === document.body) {
+            this.hostElement.appendChild(this.menuElement);
+            this.isPortaled = false;
+        }
+    }
+    handleViewportChange() {
+        if (this.isOpen) {
+            this.calculateDropdownPosition();
+        }
+    }
+    parseConfiguredMenuWidth() {
+        if (this.menuWidth === undefined || this.menuWidth === null) {
+            return {};
+        }
+        if (typeof this.menuWidth === 'number' && Number.isFinite(this.menuWidth)) {
+            return {
+                cssWidth: `${this.menuWidth}px`,
+                pixelWidth: this.menuWidth,
+            };
+        }
+        const rawWidth = String(this.menuWidth).trim();
+        if (!rawWidth) {
+            return {};
+        }
+        if (/^\d+(?:\.\d+)?$/.test(rawWidth)) {
+            const pxValue = Number(rawWidth);
+            return {
+                cssWidth: `${pxValue}px`,
+                pixelWidth: pxValue,
+            };
+        }
+        if (/^\d+(?:\.\d+)?px$/i.test(rawWidth)) {
+            return {
+                cssWidth: rawWidth,
+                pixelWidth: parseFloat(rawWidth),
+            };
+        }
+        return { cssWidth: rawWidth };
+    }
+    getMenuStyle(usesLocalMenuPosition) {
+        const configuredWidth = this.parseConfiguredMenuWidth();
+        const measuredWidth = this.computedMenuWidth > 0 ? `${this.computedMenuWidth}px` : undefined;
+        const effectiveMaxHeight = this.menuMaxHeight > 0 ? this.menuMaxHeight : (this.maxHeight || 300);
+        const baseStyles = {
+            left: `${this.menuLeft}px`,
+            maxWidth: 'calc(100vw - 16px)',
+            maxHeight: `${effectiveMaxHeight}px`,
+            visibility: usesLocalMenuPosition ? 'visible' : (this.menuLeft === 0 && this.menuTop === 0 ? 'hidden' : 'visible'),
+            top: `${this.menuTop}px`,
+        };
+        // User explicitly set a width via menuWidth prop — honour it exactly.
+        if (configuredWidth.cssWidth) {
+            return {
+                ...baseStyles,
+                width: configuredWidth.cssWidth,
+            };
+        }
+        // fullWidth — stretch to 100% of the container/viewport.
+        if (this.fullWidth) {
+            return {
+                ...baseStyles,
+                width: measuredWidth,
+                minWidth: measuredWidth,
+            };
+        }
+        // All other cases: size to content (widest option + reserved tick space).
+        return {
+            ...baseStyles,
+            width: 'max-content',
+            minWidth: measuredWidth,
+        };
+    }
+    shouldPortalMenu() {
+        // Always portal to document.body so the panel is positioned with fixed
+        // coordinates and never clipped by overflow:hidden on ancestor containers
+        // (e.g. ui-toolbar shadow host, demo cards, etc.)
+        return true;
+    }
+    calculateDropdownPosition() {
+        if (!this.hostElement || !this.isOpen || !this.menuElement)
+            return;
+        const trigger = (this.hostElement.shadowRoot?.querySelector('.dropdown-trigger') || this.hostElement.querySelector('.dropdown-trigger'));
+        if (!trigger)
+            return;
+        // Guard: Only position if trigger is visible and has size
+        const rect = trigger.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) {
+            // Hide menu if trigger is not visible
+            this.menuLeft = 0;
+            this.menuTop = 0;
+            this.computedMenuWidth = 0;
+            this.dropdownPosition = 'bottom';
+            return;
+        }
+        const configuredWidth = this.parseConfiguredMenuWidth();
+        const triggerWidth = trigger.offsetWidth || rect.width;
+        const placementWidth = !this.fitContent && configuredWidth.pixelWidth
+            ? configuredWidth.pixelWidth
+            : this.isNestedMenuVariant()
+                ? Math.max(triggerWidth, this.getNestedMenuEstimatedWidth())
+                : triggerWidth;
+        const shouldPortal = this.shouldPortalMenu();
+        if (shouldPortal && this.menuElement.parentElement !== document.body) {
+            document.body.appendChild(this.menuElement);
+            this.isPortaled = true;
+        }
+        else if (!shouldPortal && this.isPortaled) {
+            this.cleanupPortal();
+        }
+        const gap = 4;
+        const { left, top, placement: finalPlacement, availableHeight: spaceHeight } = calculateUniversalPlacement(trigger, {
+            menuWidth: placementWidth,
+            menuHeight: this.maxHeight || 300,
+            gap,
+            placement: 'auto',
+            useTransformedAncestorOffset: shouldPortal ? !this.ignoreParentPosition : true,
+        });
+        // Compute how much vertical space is actually available so the options list
+        // can be constrained and will show a scrollbar instead of overflowing.
+        const nextMaxHeight = Math.max(80, Math.min(this.maxHeight || 300, spaceHeight));
+        let nextLeft = left;
+        let nextTop = top;
+        if (!shouldPortal) {
+            // If not portaling, we need relative coordinates to host
+            // However, calculateUniversalPlacement already handles offsetParent.
+            // If host is the offsetParent, then left/top are already relative.
+            // If NOT, we might need adjustments. 
+            // Re-check the previous logic: it subtracted hostRect.left.
+            nextLeft = left;
+            nextTop = top;
+        }
+        if (this.menuLeft !== nextLeft ||
+            this.menuTop !== nextTop ||
+            this.computedMenuWidth !== triggerWidth ||
+            this.dropdownPosition !== finalPlacement ||
+            this.menuMaxHeight !== nextMaxHeight) {
+            this.menuLeft = nextLeft;
+            this.menuTop = nextTop;
+            this.computedMenuWidth = triggerWidth;
+            this.dropdownPosition = finalPlacement;
+            this.menuMaxHeight = nextMaxHeight;
+        }
+    }
+    closeDropdown = () => {
+        if (this.isOpen) {
+            this.isOpen = false;
+            this.dropdownClose.emit();
+            this.searchQuery = '';
+            this.cleanupPortal();
+        }
+    };
+    handleOptionClick = (option, event) => {
+        event.stopPropagation();
+        if (option.disabled)
+            return;
+        if (this.cascading && option.children && option.children.length > 0) {
+            if (this.isNestedMenuVariant()) {
+                const visibleLevels = this.getNestedMenuLevels(this.filterOptions(this.parsedOptions));
+                const level = visibleLevels.findIndex(levelOptions => levelOptions.some(levelOption => (levelOption.value?.toString() ?? '') === (option.value?.toString() ?? '')));
+                this.setNestedPath(level === -1 ? 0 : level, option.value?.toString() ?? '');
+                return;
+            }
+            this.toggleNode(option.value?.toString() ?? '');
+            return;
+        }
+        if (this.multiSelect) {
+            const newSelected = new Set(this.selectedValues);
+            const stringValue = option.value?.toString() ?? '';
+            if (newSelected.has(stringValue)) {
+                newSelected.delete(stringValue);
+                ariaLive.announce(`Deselected ${option.label}`);
+            }
+            else {
+                newSelected.add(stringValue);
+                ariaLive.announce(`Selected ${option.label}`);
+            }
+            this.selectedValues = newSelected;
+            this.value = Array.from(newSelected).join(',');
+        }
+        else {
+            const val = option.value?.toString() ?? '';
+            this.selectedValues = new Set([val]);
+            this.value = val;
+            this.closeDropdown();
+            this.hostElement.shadowRoot?.querySelector('.dropdown-trigger')?.focus();
+            ariaLive.announce(`Selected ${option.label}`);
+        }
+        this.emitChangeEvent();
+    };
+    toggleNode = (value) => {
+        const newExpanded = new Set(this.expandedNodes);
+        if (newExpanded.has(value)) {
+            newExpanded.delete(value);
+        }
+        else {
+            newExpanded.add(value);
+        }
+        this.expandedNodes = newExpanded;
+    };
+    handleClear = (event) => {
+        event.stopPropagation();
+        this.selectedValues = new Set();
+        this.value = '';
+        this.emitChangeEvent();
+        this.hostElement.shadowRoot?.querySelector('.dropdown-trigger')?.focus();
+    };
+    handleSearchInput = (event) => {
+        const input = event.target;
+        this.searchQuery = input.value.toLowerCase();
+    };
+    emitChangeEvent() {
+        const selectedOptions = this.getSelectedOptions();
+        this.valueChange.emit({
+            value: this.value,
+            selectedOptions,
+        });
+    }
+    getSelectedOptions() {
+        const selected = [];
+        const findSelected = (options) => {
+            options.forEach(option => {
+                if (this.selectedValues.has(option.value?.toString() ?? '')) {
+                    selected.push(option);
+                }
+                if (option.children) {
+                    findSelected(option.children);
+                }
+            });
+        };
+        findSelected(this.parsedOptions);
+        return selected;
+    }
+    getSelectedDescendantCount(option) {
+        if (!option.children)
+            return 0;
+        let count = 0;
+        const countSelected = (options) => {
+            options.forEach(o => {
+                if (this.selectedValues.has(o.value?.toString() ?? ''))
+                    count++;
+                if (o.children)
+                    countSelected(o.children);
+            });
+        };
+        countSelected(option.children);
+        return count;
+    }
+    filterOptions(options) {
+        if (!this.searchQuery)
+            return options;
+        return options
+            .filter(option => {
+            const query = this.caseSensitive ? this.searchQuery : this.searchQuery.toLowerCase();
+            const label = this.caseSensitive ? (option.label ?? '') : (option.label ?? '').toLowerCase();
+            const subtitle = this.caseSensitive ? (option.subtitle || '') : (option.subtitle || '').toLowerCase();
+            const description = this.caseSensitive ? (option.description || '') : (option.description || '').toLowerCase();
+            const group = this.caseSensitive ? (option.group || '') : (option.group || '').toLowerCase();
+            const matchesLabel = label.includes(query);
+            const matchesSubtitle = subtitle.includes(query);
+            const matchesDesc = description.includes(query);
+            const matchesGroup = group.includes(query);
+            const hasMatchingChildren = option.children && this.filterOptions(option.children).length > 0;
+            return matchesLabel || matchesSubtitle || matchesDesc || matchesGroup || hasMatchingChildren;
+        })
+            .map(option => ({
+            ...option,
+            children: option.children ? this.filterOptions(option.children) : undefined,
+        }));
+    }
+    getIconSize(type) {
+        const sizes = {
+            sm: { main: '14px', sub: '12px', marker: '16px' },
+            md: { main: '16px', sub: '14px', marker: '18px' },
+            lg: { main: '18px', sub: '16px', marker: '20px' },
+        };
+        // Defensive: fallback to 'md' if size is not a key
+        let safeSize = 'md';
+        if (this.size === 'sm' || this.size === 'md' || this.size === 'lg') {
+            safeSize = this.size;
+        }
+        return sizes[safeSize][type];
+    }
+    highlightMatches(text) {
+        if (!this.searchQuery || !text)
+            return text;
+        const query = this.searchQuery.toLowerCase();
+        const index = text.toLowerCase().indexOf(query);
+        if (index === -1)
+            return text;
+        return (h("span", null, text.substring(0, index), h("span", { class: "dropdown-search-highlight" }, text.substring(index, index + query.length)), text.substring(index + query.length)));
+    }
+    renderOption(option, level = 0, indexObj = { current: 0 }) {
+        if (option.isSeparator) {
+            return h("div", { class: "dropdown-separator" });
+        }
+        const isSelected = this.selectedValues.has(option.value?.toString() ?? '');
+        const hasChildren = !!(this.cascading && option.children && option.children.length > 0);
+        const myIndex = indexObj.current;
+        indexObj.current++;
+        const isHighlighted = myIndex === this.highlightedIndex;
+        const optionId = this.getOptionId(myIndex);
+        return (h("div", { class: "dropdown-option-wrapper", key: option.value?.toString() ?? '', role: "option", id: optionId, "aria-selected": isSelected ? 'true' : 'false' }, h("div", { class: {
+                'ui-dropdown-option': true,
+                'dropdowndata': true,
+                'ui-dropdown-option-selected': isSelected,
+                'dropdown-option-highlighted': isHighlighted,
+                'dropdown-option-disabled': !!option.disabled,
+                'dropdown-option-parent': hasChildren
+            }, style: {
+                paddingLeft: `${16}px`,
+                display: 'flex',
+                flexDirection: 'row',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                gap: '12px',
+                boxSizing: 'border-box',
+                width: '100%',
+                whiteSpace: 'nowrap',
+                ...(isSelected ? { backgroundColor: 'var(--dd-selected-bg)', color: 'var(--dd-selected-text)', borderRadius: '12px' } : {})
+            }, onClick: (e) => this.handleOptionClick(option, e), ref: (el) => {
+                if (el)
+                    this.optionsRef[myIndex] = el;
+            } }, ((this.multiSelect && !hasChildren) || option.icon) && (h("div", { class: "dropdown-option-left" }, this.multiSelect && !hasChildren && (h("div", { class: { 'dropdown-checkbox': true, 'checked': isSelected, 'dropdown-checkbox-selected': isSelected } }, isSelected && h("ui-icon", { name: "check", library: "lucide", size: this.getIconSize('sub'), color: "white" }))), option.icon && (h("span", { class: "dropdown-option-icon" }, typeof option.icon === 'string' ? (h("ui-icon", { name: option.icon, library: option.iconLibrary, size: this.getIconSize('main') })) : (option.icon))))), h("div", { class: "dropdown-option-text" }, h("div", { class: { 'dropdown-option-content': true, 'dropdown-content-parent': hasChildren } }, h("div", { class: "dropdown-option-label" }, this.highlightMatches(option.label ?? '')), (option.subtitle || option.description) && (h("div", { class: "dropdown-option-subtitle" }, this.highlightMatches(option.subtitle ?? option.description ?? ''))))), h("div", { class: "dropdown-option-right" }, option.rightTag && (h("ui-tag", { label: option.rightTag, color: option.rightTagColor || 'default', size: "sm", variant: "light", class: "dropdown-option-tag" })), option.rightIcon && (h("span", { class: "dropdown-option-right-icon" }, h("ui-icon", { name: option.rightIcon, library: option.rightIconLibrary, size: this.getIconSize('sub') }))), hasChildren && (h("div", { class: "dropdown-expand-group" }, this.multiSelect && ((() => {
+            const count = this.getSelectedDescendantCount(option);
+            return count > 0 ? h("span", { class: "dropdown-badge" }, count) : null;
+        })()), h("ui-icon", { name: "chevron-right", library: "lucide", size: this.getIconSize('sub'), class: { 'dropdown-expand-icon': true, 'expanded': this.expandedNodes.has(option.value?.toString() ?? '') } }))), !this.multiSelect && !hasChildren && this.showSelectedMarker && (h("span", { class: "ui-dropdown-selected-marker-wrap", style: !isSelected ? { visibility: 'hidden' } : {} }, h("ui-icon", { name: this.selectedMarkerIcon, library: this.selectedMarkerLibrary, size: this.getIconSize('marker'), class: "ui-dropdown-selected-marker", color: this.selectedMarkerColor || 'var(--dd-selected-icon)' }), this.selectedMarkerLabel && h("span", { class: "ui-dropdown-selected-marker-label" }, this.selectedMarkerLabel))))), hasChildren && this.expandedNodes.has(option.value?.toString() ?? '') && (h("div", { class: "dropdown-children" }, option.children?.map(child => this.renderOption(child, level + 1, indexObj))))));
+    }
+    renderChips() {
+        const selectedOptions = this.getSelectedOptions();
+        if (selectedOptions.length === 0)
+            return this.placeholder;
+        return (h("div", { class: "dropdown-chips" }, selectedOptions.map(option => (h("ui-tag", { label: option.label ?? '', size: "sm", color: "primary", variant: "light", removable: true, animation: "slide", onTagRemove: (e) => {
+                e.stopPropagation();
+                this.handleOptionClick(option, e);
+            } })))));
+    }
+    getDisplayText() {
+        if (this.selectedValues.size === 0) {
+            return this.placeholder;
+        }
+        if (this.multiSelect) {
+            if (this.chipView)
+                return this.renderChips();
+            const selectedOptions = this.getSelectedOptions();
+            if (selectedOptions.length === 1) {
+                return selectedOptions[0].label;
+            }
+            return `${selectedOptions.length} items selected`;
+        }
+        else {
+            const selectedOptions = this.getSelectedOptions();
+            if (selectedOptions.length > 0) {
+                const option = selectedOptions[0];
+                if (this.variant === 'detailed' && option.icon) {
+                    return (h("div", { class: "dropdown-trigger-content" }, h("ui-icon", { name: option.icon, library: option.iconLibrary || this.iconLibrary, size: "18px", class: "dropdown-trigger-icon" }), h("span", { class: "dropdown-trigger-label" }, option.label)));
+                }
+                return option.label;
+            }
+            return this.placeholder;
+        }
+    }
+    renderValidationSubstrate() {
+        if (this.invalid && this.errorMessage) {
+            return (h("div", { class: "dropdown-helper-text dropdown-error-text" }, h("ui-icon", { name: "alert-circle", library: "lucide", size: "12px" }), h("span", null, this.errorMessage)));
+        }
+        if (this.helperText) {
+            return h("div", { class: "dropdown-helper-text" }, this.helperText);
+        }
+        return null;
+    }
+    render() {
+        if (this.skeleton) {
+            return (h("div", { class: { 'dropdown-container': true, 'dropdown-skeleton': true, [`dropdown-${this.size}`]: true, 'dropdown-full-width': this.fullWidth, 'dropdown-fit-content': this.fitContent, [`variant-${this.variant}`]: true } }, h("div", { class: "dropdown-trigger" }, h("div", { class: "dropdown-skeleton-text" }), h("div", { class: "dropdown-skeleton-icon" }))));
+        }
+        const filteredOptions = this.filterOptions(this.parsedOptions);
+        const hasSelection = this.selectedValues.size > 0;
+        const showArrow = this.showArrow !== undefined ? this.showArrow : this.appearance !== 'button';
+        const effectiveClearable = this.clearable !== undefined ? this.clearable : (this.multiSelect && !this.chipView);
+        const indexObj = { current: 0 };
+        const activeDescendantId = this.isOpen && this.highlightedIndex >= 0 ? this.getOptionId(this.highlightedIndex) : undefined;
+        const usesLocalMenuPosition = !this.shouldPortalMenu();
+        // Always use theme variable for text color unless textColor is set and not placeholder
+        let displayStyle = {};
+        if (this.textColor && hasSelection) {
+            displayStyle.color = this.textColor;
+        }
+        else {
+            displayStyle.color = 'var(--dd-text, var(--color-on-surface, #10213a))';
+        }
+        return (h("div", { class: {
+                'dropdown-container': true,
+                [`dropdown-${this.size}`]: true,
+                [`variant-${this.variant}`]: true,
+                'dropdown-disabled': this.disabled,
+                'dropdown-open': this.isOpen,
+                'dropdown-invalid': this.invalid,
+                'dropdown-appearance-button': this.appearance === 'button',
+                'dropdown-full-width': this.fullWidth,
+                'dropdown-fit-content': this.fitContent,
+                'dropdown-has-chips': this.chipView && this.multiSelect && hasSelection,
+                'dropdown-rtl': this.rtl,
+                [`dropdown-shape-${this.shape}`]: this.shape !== 'default',
+            }, dir: this.rtl ? 'rtl' : 'ltr' }, this.label && h("label", { class: "dropdown-label" }, this.label), h("div", { class: "dropdown-trigger", onClick: this.toggleDropdown, onKeyDown: this.handleKeyDown, tabIndex: this.disabled ? -1 : 0, role: "combobox", "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-controls": "dropdown-list", "aria-label": this.placeholder, "aria-activedescendant": activeDescendantId }, h("slot", { name: "prefix" }), h("div", { class: {
+                'dropdown-display': true,
+                'dropdown-placeholder': !hasSelection,
+            }, style: displayStyle }, this.getDisplayText()), h("div", { class: "dropdown-icons" }, this.loading && h("span", { class: "dropdown-spinner" }, h("ui-icon", { name: "loader-2", library: "lucide", spin: true, size: "16px" })), hasSelection && effectiveClearable && !this.disabled && (h("span", { class: "dropdown-clear", onClick: this.handleClear, tabIndex: 0, role: "button", "aria-label": "Clear selection", onKeyDown: e => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.stopPropagation();
+                    this.handleClear(e);
+                }
+            } }, h("ui-icon", { name: "x", library: "lucide", size: this.getIconSize('sub') }))), showArrow && (h("ui-icon", { name: "chevron-down", library: "lucide", size: this.getIconSize('sub'), class: { 'dropdown-arrow': true, 'open': this.isOpen } })))), this.renderValidationSubstrate(), this.isOpen && (h("div", { class: {
+                'ui-dropdown-menu': true,
+                'ui-dropdown-menu--local': usesLocalMenuPosition,
+                'dropdown-menu-top': this.dropdownPosition === 'top',
+                [`dropdown-menu-${this.size}`]: true,
+                [`dropdown-menu-variant-${this.variant}`]: true,
+                'dropdown-menu-searchable': this.searchable,
+                'dropdown-menu-cascading': this.cascading,
+            }, id: "dropdown-list", role: "listbox", "aria-multiselectable": this.multiSelect ? 'true' : 'false', ref: el => {
+                if (el)
+                    this.menuElement = el;
+            }, style: this.getMenuStyle(usesLocalMenuPosition) }, this.searchable && (h("div", { class: "dropdown-search" }, h("div", { class: "dropdown-search-container" }, h("ui-icon", { name: "search", library: "lucide", size: "16px", class: "dropdown-search-icon" }), h("input", { type: "text", class: "dropdown-search-input", placeholder: this.searchPlaceholder, value: this.searchQuery, onInput: this.handleSearchInput, ref: el => {
+                if (el)
+                    this.searchInputRef = el;
+            }, onKeyDown: this.handleKeyDown, "aria-activedescendant": activeDescendantId })))), h("div", { class: "dropdown-options" }, this.renderBulkActions(filteredOptions), filteredOptions.length > 0 ? this.renderMenuContents(filteredOptions, indexObj) : (h("div", { class: "dropdown-empty" }, h("slot", { name: "empty-state" }, "No options found"))))))));
+    }
+    isAllSelected(options) {
+        const flattenOptions = (opts) => {
+            let result = [];
+            opts.forEach(o => {
+                result.push(o.value?.toString() ?? '');
+                if (o.children)
+                    result = [...result, ...flattenOptions(o.children)];
+            });
+            return result;
+        };
+        const allValues = flattenOptions(options);
+        if (allValues.length === 0)
+            return false;
+        return allValues.every(v => this.selectedValues.has(v));
+    }
+    toggleSelectAll(options) {
+        const flattenOptions = (opts) => {
+            let result = [];
+            opts.forEach(o => {
+                result.push(o.value?.toString() ?? '');
+                if (o.children)
+                    result = [...result, ...flattenOptions(o.children)];
+            });
+            return result;
+        };
+        const allValues = flattenOptions(options);
+        const isAll = this.isAllSelected(options);
+        if (isAll) {
+            allValues.forEach(v => this.selectedValues.delete(v));
+        }
+        else {
+            allValues.forEach(v => this.selectedValues.add(v));
+        }
+        this.selectedValues = new Set(this.selectedValues);
+        this.value = Array.from(this.selectedValues).join(',');
+        this.emitChangeEvent();
+    }
+    clearAllSelections() {
+        this.selectedValues = new Set();
+        this.value = ''; // Assuming value should also be cleared
+        this.emitChangeEvent();
+    }
+    renderBulkActions(filteredOptions) {
+        if (!this.multiSelect || this.searchQuery)
+            return null; // Only show bulk actions for multi-select when not searching
+        const allSelected = this.isAllSelected(filteredOptions);
+        const hasAnySelection = this.selectedValues.size > 0;
+        const showSelectAllAction = this.showSelectAll && filteredOptions.length > 0;
+        if (!showSelectAllAction && !hasAnySelection) {
+            return null;
+        }
+        return (h("div", { class: "dropdown-bulk-actions" }, showSelectAllAction && (h("div", { class: { 'dropdown-select-all': true, 'dropdown-select-all-with-clear': hasAnySelection }, onClick: e => { e.stopPropagation(); this.toggleSelectAll(filteredOptions); } }, h("div", { class: { 'dropdown-checkbox': true, 'dropdown-checkbox-selected': allSelected } }, allSelected && h("ui-icon", { name: "check", library: "lucide", size: "12px" })), h("span", null, this.selectAllLabel))), hasAnySelection && (h("div", { class: "dropdown-clear-all", onClick: e => { e.stopPropagation(); this.clearAllSelections(); } }, h("ui-icon", { name: "trash-2", library: "lucide", size: "14px" }), h("span", null, "Clear All")))));
+    }
+    renderNestedMenuContents(options, indexObj) {
+        const levels = this.getNestedMenuLevels(options);
+        return (h("div", { class: "dropdown-nested-columns" }, levels.map((levelOptions, levelIndex) => (h("div", { class: "dropdown-nested-panel", key: `nested-level-${levelIndex}` }, levelOptions.map(option => {
+            const hasChildren = !!option.children?.length;
+            const value = option.value?.toString() ?? '';
+            const isSelected = this.selectedValues.has(value);
+            const isActive = this.nestedPath[levelIndex] === value;
+            const myIndex = indexObj.current;
+            indexObj.current++;
+            const isHighlighted = myIndex === this.highlightedIndex;
+            const optionId = this.getOptionId(myIndex);
+            return (h("div", { class: "dropdown-option-wrapper", key: `${value}-${levelIndex}`, role: "option", id: optionId, "aria-selected": isSelected ? 'true' : 'false' }, h("div", { class: {
+                    'ui-dropdown-option': true,
+                    'dropdowndata': true,
+                    'dropdown-nested-option': true,
+                    'ui-dropdown-option-selected': isSelected,
+                    'dropdown-option-highlighted': isHighlighted,
+                    'dropdown-option-disabled': !!option.disabled,
+                    'dropdown-option-parent': hasChildren,
+                    'dropdown-nested-option-active': isActive,
+                }, onMouseEnter: () => {
+                    if (hasChildren) {
+                        this.setNestedPath(levelIndex, value);
+                    }
+                }, onClick: (e) => this.handleOptionClick(option, e), ref: (el) => {
+                    if (el)
+                        this.optionsRef[myIndex] = el;
+                } }, ((this.multiSelect && !hasChildren) || option.icon) && (h("div", { class: "dropdown-option-left" }, this.multiSelect && !hasChildren && (h("div", { class: { 'dropdown-checkbox': true, 'checked': isSelected, 'dropdown-checkbox-selected': isSelected } }, isSelected && h("ui-icon", { name: "check", library: "lucide", size: this.getIconSize('sub'), color: "white" }))), option.icon && (h("span", { class: "dropdown-option-icon" }, typeof option.icon === 'string' ? (h("ui-icon", { name: option.icon, library: option.iconLibrary, size: this.getIconSize('main') })) : (option.icon))))), h("div", { class: "dropdown-option-text" }, h("div", { class: "dropdown-option-content" }, h("div", { class: "dropdown-option-label" }, this.highlightMatches(option.label ?? '')), (option.subtitle || option.description) && (h("div", { class: "dropdown-option-subtitle" }, this.highlightMatches(option.subtitle ?? option.description ?? ''))))), h("div", { class: "dropdown-option-right" }, option.rightTag && (h("ui-tag", { label: option.rightTag, color: option.rightTagColor || 'default', size: "sm", variant: "light", class: "dropdown-option-tag" })), hasChildren && (h("ui-icon", { name: "chevron-right", library: "lucide", size: this.getIconSize('sub'), class: { 'dropdown-expand-icon': true, 'expanded': isActive } })), !this.multiSelect && !hasChildren && this.showSelectedMarker && (h("span", { class: "ui-dropdown-selected-marker-wrap", style: !isSelected ? { visibility: 'hidden' } : {} }, h("ui-icon", { name: this.selectedMarkerIcon, library: this.selectedMarkerLibrary, size: this.getIconSize('marker'), class: "ui-dropdown-selected-marker", color: this.selectedMarkerColor || 'var(--dd-selected-icon)' }), this.selectedMarkerLabel && h("span", { class: "ui-dropdown-selected-marker-label" }, this.selectedMarkerLabel)))))));
+        }))))));
+    }
+    renderMenuContents(options, indexObj) {
+        if (this.isNestedMenuVariant()) {
+            return this.renderNestedMenuContents(options, indexObj);
+        }
+        const rendered = [];
+        let lastGroup = null;
+        const displayOptions = this.virtualScroll ? options.slice(0, 50) : options;
+        displayOptions.forEach(option => {
+            if (option.group && option.group !== lastGroup) {
+                rendered.push(h("div", { class: "dropdown-group-header" }, option.group));
+                lastGroup = option.group;
+            }
+            rendered.push(this.renderOption(option, 0, indexObj));
+        });
+        if (this.virtualScroll && options.length > 50) {
+            rendered.push(h("div", { class: "dropdown-more-info" }, "Showing 50 of ", options.length, " items. Use search to find more."));
+        }
+        return rendered;
+    }
+    static get is() { return "ui-dropdown"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["./dropdown.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["dropdown.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "options": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | DropdownOption[]",
+                    "resolved": "DropdownOption[] | string",
+                    "references": {
+                        "DropdownOption": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/dropdown/types.ts::DropdownOption",
+                            "referenceLocation": "DropdownOption"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Options as JSON string or DropdownOption array"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "options",
+                "defaultValue": "[]"
+            },
+            "placeholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Placeholder text"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "placeholder",
+                "defaultValue": "'Select an option'"
+            },
+            "multiSelect": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enable multi-select mode"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "multi-select",
+                "defaultValue": "false"
+            },
+            "cascading": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enable cascading/hierarchical selection"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "cascading",
+                "defaultValue": "false"
+            },
+            "value": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Selected value(s) - string for single, comma-separated for multi"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value",
+                "defaultValue": "''"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Disabled state"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "searchable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Show search/filter input"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "searchable",
+                "defaultValue": "false"
+            },
+            "maxHeight": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Maximum height of dropdown (in pixels)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-height",
+                "defaultValue": "300"
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "BasicSize",
+                    "resolved": "\"default\" | \"large\" | \"lg\" | \"md\" | \"medium\" | \"sm\" | \"small\"",
+                    "references": {
+                        "BasicSize": {
+                            "location": "import",
+                            "path": "../../types",
+                            "id": "src/types/index.ts::BasicSize",
+                            "referenceLocation": "BasicSize"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Size variant"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "size",
+                "defaultValue": "'md'"
+            },
+            "appearance": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'dropdown' | 'button'",
+                    "resolved": "\"button\" | \"dropdown\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Appearance: default dropdown or button-like (no arrow)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "appearance",
+                "defaultValue": "'dropdown'"
+            },
+            "variant": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'default' | 'glass' | 'detailed' | 'nested-menu' | 'toggle'",
+                    "resolved": "\"default\" | \"detailed\" | \"glass\" | \"nested-menu\" | \"toggle\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Aesthetic variant"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "variant",
+                "defaultValue": "'default'"
+            },
+            "chipView": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Use chips for multi-select display"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "chip-view",
+                "defaultValue": "false"
+            },
+            "showArrow": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Controls visibility of the arrow icon. If false, no arrow is shown.\r\nDefaults to true for dropdown appearance; false when appearance is 'button'."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-arrow"
+            },
+            "ignoreParentPosition": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, dropdown positioning ignores transformed/positioned parent offsets.\r\nUse this when the menu is portaled and should stay anchored to viewport coordinates."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "ignore-parent-position",
+                "defaultValue": "true"
+            },
+            "clearable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Show clear (\u2715) button when a value is selected.\r\n- When not set (default): automatically shown for multi-select, hidden for single-select.\r\n- Set to `true`  : always show the clear button (both single & multi).\r\n- Set to `false` : always hide the clear button (both single & multi)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "clearable"
+            },
+            "fullWidth": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, the dropdown will take up the full width of its container."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "full-width",
+                "defaultValue": "false"
+            },
+            "fitContent": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, the dropdown width fits its longest option (max-content)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "fit-content",
+                "defaultValue": "false"
+            },
+            "menuWidth": {
+                "type": "any",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | number",
+                    "resolved": "number | string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Optional width for the dropdown options panel.\r\nAccepts a number (pixels) or any valid CSS width value such as `320px`, `24rem`, or `min(28rem, 90vw)`.\r\nBy default, the menu matches the trigger width."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "menu-width"
+            },
+            "loading": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Loading state"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "loading",
+                "defaultValue": "false"
+            },
+            "invalid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Validation state"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "invalid",
+                "defaultValue": "false"
+            },
+            "helperText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Helper text / validation message"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "helper-text"
+            },
+            "errorMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Error message to show when invalid"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "error-message"
+            },
+            "searchPlaceholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Placeholder for the search input"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "search-placeholder",
+                "defaultValue": "'Search...'"
+            },
+            "iconLibrary": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Default icon library for option icons (e.g. 'lucide', 'ionicons')"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "icon-library",
+                "defaultValue": "'ionicons'"
+            },
+            "showPath": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, show the full hierarchy path in selected value (for cascading)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-path",
+                "defaultValue": "false"
+            },
+            "highFidelity": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Use high-fidelity animation (Framer-like physics)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "high-fidelity",
+                "defaultValue": "true"
+            },
+            "rtl": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "RTL support"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "rtl",
+                "defaultValue": "false"
+            },
+            "shape": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'default' | 'square' | 'rounded' | 'pill'",
+                    "resolved": "\"default\" | \"pill\" | \"rounded\" | \"square\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Shape variant (inherits from design system or parent)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "shape",
+                "defaultValue": "'default'"
+            },
+            "showSelectedMarker": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, shows a checkmark (tick) next to the selected item in single-select mode."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-selected-marker",
+                "defaultValue": "true"
+            },
+            "selectedMarkerIcon": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Custom icon for the selection marker"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-marker-icon",
+                "defaultValue": "'check'"
+            },
+            "selectedMarkerLibrary": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Icon library for the selection marker icon"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-marker-library",
+                "defaultValue": "'lucide'"
+            },
+            "selectedMarkerLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Optional label text shown after the checkmark on the selected item."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-marker-label",
+                "defaultValue": "''"
+            },
+            "selectedMarkerColor": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Color for the selection marker icon. Defaults to the selected state color token."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-marker-color",
+                "defaultValue": "''"
+            },
+            "expandAll": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, all nodes in a cascading dropdown will be expanded by default."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "expand-all",
+                "defaultValue": "false"
+            },
+            "skeleton": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, shows a skeleton loading state for the trigger"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "skeleton",
+                "defaultValue": "false"
+            },
+            "showSelectAll": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, shows a \"Select All\" option in multi-select mode"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-select-all",
+                "defaultValue": "false"
+            },
+            "selectAllLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Label for the Select All option"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "select-all-label",
+                "defaultValue": "'Select All'"
+            },
+            "textColor": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Custom text color for the dropdown display"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "text-color",
+                "defaultValue": "''"
+            },
+            "virtualScroll": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, enables virtual scrolling (renders only a subset of items for performance)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "virtual-scroll",
+                "defaultValue": "false"
+            },
+            "caseSensitive": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If true, search filtering is case-sensitive"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "case-sensitive",
+                "defaultValue": "false"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Label text shown above the dropdown"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label",
+                "defaultValue": "''"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isOpen": {},
+            "parsedOptions": {},
+            "selectedValues": {},
+            "searchQuery": {},
+            "expandedNodes": {},
+            "dropdownPosition": {},
+            "menuLeft": {},
+            "menuTop": {},
+            "computedMenuWidth": {},
+            "menuMaxHeight": {},
+            "highlightedIndex": {},
+            "nestedPath": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "valueChange",
+                "name": "valueChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when value changes"
+                },
+                "complexType": {
+                    "original": "DropdownChangeEvent",
+                    "resolved": "DropdownChangeEvent",
+                    "references": {
+                        "DropdownChangeEvent": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/dropdown/types.ts::DropdownChangeEvent",
+                            "referenceLocation": "DropdownChangeEvent"
+                        }
+                    }
+                }
+            }, {
+                "method": "dropdownOpen",
+                "name": "dropdownOpen",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when dropdown opens"
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "dropdownClose",
+                "name": "dropdownClose",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when dropdown closes"
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "open": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Programmatically open the dropdown menu",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "hostElement"; }
+    static get watchers() {
+        return [{
+                "propName": "options",
+                "methodName": "handleOptionsChange"
+            }, {
+                "propName": "value",
+                "methodName": "handleValueChange"
+            }, {
+                "propName": "searchQuery",
+                "methodName": "handleSearchQueryChange"
+            }];
+    }
+}