atomicuilibrary 0.0.1

package/dist/collection/components/popover/popover.js

@@ -0,0 +1,1449 @@
+import { h } from "@stencil/core";
+import { sanitizeHTML } from "../../utils/security";
+import { FocusTrap } from "../../utils/focus-trap";
+import { calculateUniversalPlacement, autoUpdate } from "../../utils/dom";
+export class Popover {
+    element;
+    /** Popover heading text */
+    heading = '';
+    /**
+     * The target element to anchor the popover to.
+     * Can be a CSS selector (string) or a direct HTMLElement reference.
+     * If not provided, it will use the element in the 'trigger' slot or its first child.
+     */
+    target;
+    /** Popover content (HTML string). Use this for simple text or if you can't use the 'content' slot. */
+    content = '';
+    /** Controlled open state. */
+    open = false;
+    /** Disabled state. If true, popover will not show. */
+    disabled = false;
+    /**
+     * Trigger type: 'click' | 'hover' | 'focus' | 'manual'
+     * 'manual' = only show/hide via method calls
+     */
+    trigger = 'click';
+    /** Placement of popover */
+    placement = 'top';
+    /** Show arrow */
+    showArrow = true;
+    /** Popover width */
+    width = '280px';
+    /** Animation type */
+    animation = 'scale';
+    /** Show close button */
+    showCloseButton = false;
+    /** Show backdrop */
+    backdrop = false;
+    /**
+     * Visual variant.
+     * 'light' | 'dark' | 'success' | 'warning' | 'error' | 'info'
+     */
+    variant = 'light';
+    /**
+     * ARIA role for the popover panel.
+     * Use 'tooltip' for non-interactive hover hints, 'menu' for menus, 'dialog' for rich content.
+     */
+    popoverRole = 'dialog';
+    /**
+     * Delay in ms before showing on hover (0 = immediate)
+     */
+    showDelay = 0;
+    /**
+     * Delay in ms before hiding on hover
+     */
+    hideDelay = 200;
+    /**
+     * Close popover when window is scrolled
+     */
+    closeOnScroll = false;
+    /**
+     * Allow Escape key to close the popover (default: true)
+     */
+    closeOnEsc = true;
+    /**
+     * Maximum height of the popover body. If content exceeds this, it scrolls.
+     */
+    maxHeight = 'none';
+    /**
+     * When hover trigger is used, allow cursor to move into the popover without closing it.
+     * Set to false for pure tooltip behaviour.
+     */
+    interactive = true;
+    /** Loading state */
+    loading = false;
+    /** Skeleton state */
+    skeleton = false;
+    /** Distance between popover and trigger (in pixels) */
+    offset = 12;
+    /** Size of the arrow in pixels */
+    arrowSize = 10;
+    /** Close popover when clicking outside */
+    closeOnOutsideClick = true;
+    /** Close popover when focus leaves it */
+    closeOnBlur = true;
+    /** Match the width of the trigger element */
+    matchTriggerWidth = false;
+    /** Enable auto-flipping when hitting screen boundaries */
+    flip = true;
+    /** Enable auto-shifting (clamping) to stay inside viewport */
+    shift = true;
+    /** Boundary element for collision detection */
+    boundary = 'viewport';
+    /** Padding from boundary edges */
+    padding = 24;
+    /** Fallback placements for flipping (e.g. "top, bottom") */
+    fallbackPlacements;
+    /** Automatically choose the best placement based on available space */
+    autoPlacement = false;
+    /** Positioning strategy */
+    strategy = 'fixed';
+    /** Optional z-index for the popover panel */
+    zIndex = 21000;
+    /** Emitted before popover shows. Call event.preventDefault() to cancel. */
+    uiBeforeOpen;
+    /** Emitted when popover shows */
+    uiOpen;
+    /** Emitted before popover hides. Call event.preventDefault() to cancel. */
+    uiBeforeClose;
+    /** Emitted when popover hides */
+    uiClose;
+    /** Emitted when toggled */
+    uiToggle;
+    currentPlacement = 'top';
+    popoverStyles = {};
+    arrowStyles = {};
+    targetElement;
+    popoverContent;
+    arrowElement;
+    hideTimeout;
+    showTimeout;
+    focusTrap;
+    cleanupAutoUpdate;
+    resizeObserver;
+    latestSizeData = { width: '', maxWidth: '', maxHeight: '' };
+    updateRetries = 0;
+    componentWillLoad() {
+        this.currentPlacement = this.placement;
+    }
+    componentDidLoad() {
+        this.setupTrigger();
+        this.popoverContent = this.element.shadowRoot?.querySelector('.popover');
+        this.arrowElement = this.element.shadowRoot?.querySelector('.popover-arrow');
+        if (this.popoverContent) {
+            this.resizeObserver = new ResizeObserver(() => {
+                if (this.open)
+                    this.updatePosition();
+            });
+            this.resizeObserver.observe(this.popoverContent);
+        }
+        window.addEventListener('keydown', this.handleGlobalKeyDown);
+    }
+    componentDidUpdate() {
+        if (this.open && !this.cleanupAutoUpdate) {
+            this.startAutoUpdate();
+        }
+    }
+    disconnectedCallback() {
+        this.cleanup();
+        if (this.cleanupAutoUpdate) {
+            this.cleanupAutoUpdate();
+        }
+        window.removeEventListener('keydown', this.handleGlobalKeyDown);
+        if (this.focusTrap) {
+            this.focusTrap.deactivate();
+        }
+    }
+    visibilityChanged(newValue) {
+        if (newValue) {
+            if (this.disabled) {
+                this.open = false;
+                return;
+            }
+            this.handleOpen();
+        }
+        else {
+            this.handleClose();
+        }
+    }
+    handleTriggerConfigChange() {
+        this.cleanup();
+        this.setupTrigger();
+    }
+    handleOpen() {
+        if (!this.targetElement) {
+            this.setupTrigger();
+        }
+        this.popoverContent = this.element.shadowRoot?.querySelector('.popover');
+        this.arrowElement = this.element.shadowRoot?.querySelector('.popover-arrow');
+        if (this.popoverContent && !this.resizeObserver) {
+            this.resizeObserver = new ResizeObserver(() => {
+                if (this.open)
+                    this.updatePosition();
+            });
+            this.resizeObserver.observe(this.popoverContent);
+        }
+        requestAnimationFrame(() => {
+            this.startAutoUpdate();
+            this.updateAriaAttributes(true);
+            // Add outside click listener only when open
+            if (this.closeOnOutsideClick) {
+                // Use a sm timeout to avoid capturing the same click that opened it
+                setTimeout(() => {
+                    document.addEventListener('click', this.handleOutsideClick);
+                }, 10);
+            }
+            if (this.backdrop || this.showCloseButton || this.trigger === 'click') {
+                requestAnimationFrame(() => {
+                    this.initFocusTrap();
+                    if (this.focusTrap)
+                        this.focusTrap.activate();
+                });
+            }
+            this.uiOpen.emit();
+        });
+    }
+    handleClose() {
+        if (this.cleanupAutoUpdate) {
+            this.cleanupAutoUpdate();
+            this.cleanupAutoUpdate = undefined;
+        }
+        document.removeEventListener('click', this.handleOutsideClick);
+        if (this.focusTrap) {
+            this.focusTrap.deactivate();
+        }
+        this.updateAriaAttributes(false);
+        this.uiClose.emit();
+    }
+    updateAriaAttributes(expanded) {
+        if (this.targetElement) {
+            this.targetElement.setAttribute('aria-expanded', expanded.toString());
+            this.targetElement.setAttribute('aria-haspopup', this.popoverRole === 'menu' ? 'menu' : 'true');
+        }
+    }
+    initFocusTrap() {
+        if (!this.popoverContent)
+            return;
+        if (!this.focusTrap) {
+            this.focusTrap = new FocusTrap(this.popoverContent, {
+                initialFocus: this.popoverContent,
+                returnFocus: this.targetElement,
+                escapeDeactivates: true,
+                clickOutsideDeactivates: !this.backdrop
+            });
+        }
+    }
+    setupTrigger() {
+        // 1. Check for external target via selector or reference
+        if (this.target) {
+            if (typeof this.target === 'string') {
+                this.targetElement = document.querySelector(this.target);
+            }
+            else {
+                this.targetElement = this.target;
+            }
+        }
+        // 2. Fallback to slots if no external target
+        if (!this.targetElement) {
+            const triggerSlot = this.element.shadowRoot?.querySelector('slot[name="trigger"]');
+            const defaultSlot = this.element.shadowRoot?.querySelector('slot:not([name])');
+            const getAssignedElement = (slot) => {
+                const elements = slot?.assignedElements();
+                return elements?.length > 0 ? elements[0] : null;
+            };
+            this.targetElement = getAssignedElement(triggerSlot) || getAssignedElement(defaultSlot);
+        }
+        // 3. Last fallback: the component itself
+        if (!this.targetElement) {
+            this.targetElement = this.element;
+        }
+        if (this.targetElement && this.trigger !== 'manual') {
+            // Accessibility augmentation for non-buttons
+            if (!['BUTTON', 'A', 'INPUT', 'SELECT', 'TEXTAREA'].includes(this.targetElement.tagName)) {
+                if (!this.targetElement.hasAttribute('role'))
+                    this.targetElement.setAttribute('role', 'button');
+                if (!this.targetElement.hasAttribute('tabindex'))
+                    this.targetElement.setAttribute('tabindex', '0');
+            }
+            if (this.trigger === 'click') {
+                this.targetElement.addEventListener('click', this.handleTriggerClick);
+                this.targetElement.addEventListener('keydown', this.handleTargetKeyDown);
+            }
+            else if (this.trigger === 'hover') {
+                this.targetElement.addEventListener('mouseenter', this.handleMouseEnter);
+                this.targetElement.addEventListener('mouseleave', this.handleMouseLeave);
+                this.targetElement.addEventListener('focusin', this.handleFocusIn);
+                this.targetElement.addEventListener('focusout', this.handleFocusOut);
+            }
+            else if (this.trigger === 'focus') {
+                this.targetElement.addEventListener('focusin', this.handleFocusIn);
+                this.targetElement.addEventListener('focusout', this.handleFocusOut);
+            }
+            this.updateAriaAttributes(this.open);
+        }
+    }
+    handleTargetKeyDown = (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            this.toggle();
+        }
+    };
+    cleanup() {
+        if (!this.targetElement)
+            return;
+        this.targetElement.removeEventListener('click', this.handleTriggerClick);
+        this.targetElement.removeEventListener('keydown', this.handleTargetKeyDown);
+        this.targetElement.removeEventListener('mouseenter', this.handleMouseEnter);
+        this.targetElement.removeEventListener('mouseleave', this.handleMouseLeave);
+        this.targetElement.removeEventListener('focusin', this.handleFocusIn);
+        this.targetElement.removeEventListener('focusout', this.handleFocusOut);
+        document.removeEventListener('click', this.handleOutsideClick);
+        if (this.resizeObserver) {
+            this.resizeObserver.disconnect();
+            this.resizeObserver = undefined;
+        }
+    }
+    handleTriggerClick = (e) => {
+        e.stopPropagation();
+        if (this.trigger === 'click') {
+            this.toggle();
+        }
+    };
+    handleFocusIn = () => {
+        this.show();
+    };
+    handleFocusOut = () => {
+        this.hide();
+    };
+    handleOutsideClick = (event) => {
+        if (this.targetElement?.contains(event.target))
+            return;
+        if (this.popoverContent?.contains(event.target))
+            return;
+        if (this.open)
+            this.hide();
+    };
+    handleMouseEnter = () => {
+        if (this.disabled)
+            return;
+        clearTimeout(this.hideTimeout);
+        if (this.showDelay > 0) {
+            this.showTimeout = setTimeout(() => this.show(), this.showDelay);
+        }
+        else {
+            this.show();
+        }
+    };
+    handleMouseLeave = () => {
+        clearTimeout(this.showTimeout);
+        this.hideTimeout = setTimeout(() => this.hide(), this.hideDelay);
+    };
+    handlePopoverMouseEnter = () => {
+        if (this.trigger === 'hover' && this.interactive) {
+            clearTimeout(this.hideTimeout);
+            clearTimeout(this.showTimeout);
+        }
+    };
+    handlePopoverMouseLeave = () => {
+        if (this.trigger === 'hover' && this.interactive) {
+            this.handleMouseLeave();
+        }
+    };
+    handleGlobalKeyDown = (e) => {
+        if (this.open && this.closeOnEsc && e.key === 'Escape') {
+            e.stopPropagation();
+            this.hide();
+        }
+    };
+    startAutoUpdate() {
+        if (this.cleanupAutoUpdate)
+            this.cleanupAutoUpdate();
+        // The panel is conditionally rendered ({this.open && ...}).
+        this.popoverContent = this.element.shadowRoot?.querySelector('.popover');
+        if (this.showArrow) {
+            this.arrowElement = this.element.shadowRoot?.querySelector('.popover-arrow');
+        }
+        if (!this.targetElement || !this.popoverContent)
+            return;
+        this.cleanupAutoUpdate = autoUpdate(this.targetElement, this.popoverContent, () => this.updatePosition(), { animationFrame: true });
+    }
+    async updatePosition() {
+        // Always re-query the panel and arrow in case they were null during initial mount
+        if (!this.popoverContent) {
+            this.popoverContent = this.element.shadowRoot?.querySelector('.popover');
+        }
+        if (this.showArrow && !this.arrowElement) {
+            this.arrowElement = this.element.shadowRoot?.querySelector('.popover-arrow');
+        }
+        if (!this.open || !this.popoverContent || !this.targetElement) {
+            this.updateRetries = 0;
+            return;
+        }
+        // Double-check dimensions - if 0, we might need a retry (like Tooltip component does)
+        if (this.popoverContent.offsetWidth === 0 && this.updateRetries < 5) {
+            this.updateRetries++;
+            requestAnimationFrame(() => this.updatePosition());
+            return;
+        }
+        this.updateRetries = 0;
+        const { left, top, placement, availableHeight, availableWidth, arrowX, arrowY } = calculateUniversalPlacement(this.targetElement, {
+            menuWidth: this.popoverContent.offsetWidth,
+            menuHeight: this.popoverContent.offsetHeight,
+            gap: this.offset,
+            placement: this.autoPlacement ? 'auto' : this.placement.split('-')[0],
+            align: this.placement.includes('start') ? 'start' : (this.placement.includes('end') ? 'end' : 'center'),
+            padding: this.padding
+        });
+        this.currentPlacement = placement;
+        // Constrain size based on available space
+        this.latestSizeData = {
+            width: this.width,
+            maxWidth: `${Math.min(window.innerWidth - (this.padding * 2), availableWidth)}px`,
+            maxHeight: this.maxHeight !== 'none' ? this.maxHeight : `${availableHeight}px`,
+        };
+        const sizeData = this.latestSizeData;
+        this.popoverStyles = {
+            position: this.strategy,
+            left: `${left}px`,
+            top: `${top}px`,
+            width: this.matchTriggerWidth ? `${this.targetElement.offsetWidth}px` : (sizeData.width || this.width),
+            minWidth: '160px',
+            maxWidth: sizeData.maxWidth,
+            maxHeight: sizeData.maxHeight,
+            visibility: 'visible',
+            opacity: '1'
+        };
+        if (this.showArrow && this.arrowElement) {
+            const side = placement;
+            const staticSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[side];
+            const halfSize = Math.round(this.arrowSize / 2);
+            this.arrowStyles = {
+                top: '',
+                right: '',
+                bottom: '',
+                left: '',
+                ...(side === 'top' || side === 'bottom' ?
+                    { left: `${arrowX}px`, transform: 'translateX(-50%) rotate(45deg)' } :
+                    { top: `${arrowY}px`, transform: 'translateY(-50%) rotate(45deg)' }),
+                [staticSide]: `-${halfSize}px`,
+            };
+        }
+    }
+    async reposition() {
+        return this.updatePosition();
+    }
+    async computePlacement() {
+        return this.currentPlacement;
+    }
+    async show() {
+        if (this.disabled)
+            return;
+        if (this.uiBeforeOpen) {
+            const event = this.uiBeforeOpen.emit();
+            if (event && event.defaultPrevented)
+                return;
+        }
+        this.open = true;
+    }
+    async hide() {
+        if (this.uiBeforeClose) {
+            const event = this.uiBeforeClose.emit();
+            if (event && event.defaultPrevented)
+                return;
+        }
+        this.open = false;
+    }
+    async toggle() {
+        if (this.disabled)
+            return;
+        if (this.open) {
+            await this.hide();
+        }
+        else {
+            await this.show();
+        }
+        if (this.uiToggle)
+            this.uiToggle.emit({ open: this.open });
+    }
+    getPopoverStyle() {
+        return {
+            '--ui-popover-arrow-size': `${this.arrowSize}px`,
+            zIndex: this.zIndex ? `${this.zIndex}` : undefined,
+        };
+    }
+    render() {
+        const popoverClasses = {
+            'popover': true,
+            'popover-visible': this.open,
+            'popover-loading': this.loading,
+            'popover-skeleton': this.skeleton,
+            [`popover-${this.currentPlacement}`]: true,
+            [`popover-${this.variant}`]: true,
+            [`popover-anim-${this.animation}`]: true,
+        };
+        const finalPopoverStyle = {
+            ...this.getPopoverStyle(),
+            ...this.popoverStyles
+        };
+        return (h("div", { key: '0f7778a7317e7842be132860b1dc61b611fa247d', class: "popover-wrapper" }, h("div", { key: '2df4f3624d7335dbb9149b169778dfe288c4ff57', class: "popover-trigger" }, h("slot", { key: 'e0058a8f0c58e229df36e2ef47a402e4cf9e81dd', name: "trigger" }), h("slot", { key: '49c41549a41f352f0b94e6ae4dbde48435742ebc' })), this.backdrop && this.open && (h("div", { key: '51851882bc67bd5a1a88d7a9f8bd44df99e3dee6', class: "popover-backdrop", onClick: () => this.hide() })), this.open && (h("div", { key: 'bd82cf9d153a7b228ac7696e407bb8a0d36ae942', class: popoverClasses, style: finalPopoverStyle, onMouseEnter: () => this.handlePopoverMouseEnter(), onMouseLeave: () => this.handlePopoverMouseLeave(), role: this.popoverRole, "aria-modal": this.backdrop ? 'true' : 'false', "aria-label": this.heading || undefined }, this.showArrow && h("div", { key: '545cb01f513e171e3d79a664ea57c5cbee6b5d07', class: "popover-arrow", style: this.arrowStyles }), h("div", { key: 'bc8a9f93d49c2d1c201203728e731ef5a2850602', class: "popover-inner" }, (this.heading || this.showCloseButton) && (h("div", { key: '9dee577314cc88f1bad7372006e593f34fa1a3fc', class: "popover-header" }, this.heading && h("div", { key: '7b0b3be1e8f6b0949969172eb74702034c661f6a', class: "popover-title" }, this.heading), this.showCloseButton && (h("ui-button", { key: 'd6dcc9b87b330797f6e29bf711df0504b386f5cb', variant: "ghost", size: "xxs", iconOnly: true, class: "popover-close", onClick: () => this.hide(), ariaLabel: "Close", icon: "x", iconLibrary: "lucide", iconSize: "14px" })))), h("div", { key: '3639ca2119db19c98ce70fd11afe8ba4451cad2c', class: "popover-body", style: { maxHeight: this.maxHeight, overflowY: this.maxHeight !== 'none' ? 'auto' : undefined } }, h("slot", { key: '43b5f442af61f83b9342a8a704a625155aabb0d3', name: "content" }), this.content && h("div", { key: '1bd964f0709f66c335bfaaafe1bbe268554be279', innerHTML: sanitizeHTML(this.content) })), h("slot", { key: 'da80a35ef26a42ab2830e84ac81cdca2aef348f2', name: "footer" }))))));
+    }
+    static get is() { return "ui-popover"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["popover.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["popover.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "heading": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Popover heading text"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "heading",
+                "defaultValue": "''"
+            },
+            "target": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | HTMLElement",
+                    "resolved": "HTMLElement | string",
+                    "references": {
+                        "HTMLElement": {
+                            "location": "global",
+                            "id": "global::HTMLElement"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "The target element to anchor the popover to. \r\nCan be a CSS selector (string) or a direct HTMLElement reference.\r\nIf not provided, it will use the element in the 'trigger' slot or its first child."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "target"
+            },
+            "content": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Popover content (HTML string). Use this for simple text or if you can't use the 'content' slot."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "content",
+                "defaultValue": "''"
+            },
+            "open": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Controlled open state."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "open",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Disabled state. If true, popover will not show."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "trigger": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "TriggerType",
+                    "resolved": "\"click\" | \"focus\" | \"hover\" | \"manual\"",
+                    "references": {
+                        "TriggerType": {
+                            "location": "import",
+                            "path": "../../types/common.type",
+                            "id": "src/types/common.type.d.ts::TriggerType",
+                            "referenceLocation": "TriggerType"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Trigger type: 'click' | 'hover' | 'focus' | 'manual'\r\n'manual' = only show/hide via method calls"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "trigger",
+                "defaultValue": "'click'"
+            },
+            "placement": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "FourSidePosition|FourCornerPosition | 'left-start' | 'left-end' | 'right-start' | 'right-end'",
+                    "resolved": "\"bottom\" | \"bottom-left\" | \"bottom-right\" | \"left\" | \"left-end\" | \"left-start\" | \"right\" | \"right-end\" | \"right-start\" | \"top\" | \"top-left\" | \"top-right\"",
+                    "references": {
+                        "FourSidePosition": {
+                            "location": "import",
+                            "path": "../../types/common.type",
+                            "id": "src/types/common.type.d.ts::FourSidePosition",
+                            "referenceLocation": "FourSidePosition"
+                        },
+                        "FourCornerPosition": {
+                            "location": "import",
+                            "path": "../../types/common.type",
+                            "id": "src/types/common.type.d.ts::FourCornerPosition",
+                            "referenceLocation": "FourCornerPosition"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Placement of popover"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "placement",
+                "defaultValue": "'top'"
+            },
+            "showArrow": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Show arrow"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-arrow",
+                "defaultValue": "true"
+            },
+            "width": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Popover width"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "width",
+                "defaultValue": "'280px'"
+            },
+            "animation": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'fade' | 'scale' | 'slide' | 'none'",
+                    "resolved": "\"fade\" | \"none\" | \"scale\" | \"slide\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Animation type"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "animation",
+                "defaultValue": "'scale'"
+            },
+            "showCloseButton": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Show close button"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-close-button",
+                "defaultValue": "false"
+            },
+            "backdrop": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Show backdrop"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "backdrop",
+                "defaultValue": "false"
+            },
+            "variant": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'light' | 'dark' | StatusColor",
+                    "resolved": "\"borderless\" | \"danger\" | \"dark\" | \"default\" | \"elevated\" | \"error\" | \"flat\" | \"ghost\" | \"glass\" | \"info\" | \"inverse\" | \"light\" | \"loading\" | \"neutral\" | \"none\" | \"outline\" | \"plain\" | \"primary\" | \"raised\" | \"secondary\" | \"soft\" | \"sovereign\" | \"success\" | \"surface\" | \"tertiary\" | \"warning\"",
+                    "references": {
+                        "StatusColor": {
+                            "location": "import",
+                            "path": "../../types/common.type",
+                            "id": "src/types/common.type.d.ts::StatusColor",
+                            "referenceLocation": "StatusColor"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Visual variant.\r\n'light' | 'dark' | 'success' | 'warning' | 'error' | 'info'"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "variant",
+                "defaultValue": "'light'"
+            },
+            "popoverRole": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'dialog' | 'tooltip' | 'menu' | 'listbox'",
+                    "resolved": "\"dialog\" | \"listbox\" | \"menu\" | \"tooltip\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "ARIA role for the popover panel.\r\nUse 'tooltip' for non-interactive hover hints, 'menu' for menus, 'dialog' for rich content."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "popover-role",
+                "defaultValue": "'dialog'"
+            },
+            "showDelay": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Delay in ms before showing on hover (0 = immediate)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-delay",
+                "defaultValue": "0"
+            },
+            "hideDelay": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Delay in ms before hiding on hover"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "hide-delay",
+                "defaultValue": "200"
+            },
+            "closeOnScroll": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Close popover when window is scrolled"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "close-on-scroll",
+                "defaultValue": "false"
+            },
+            "closeOnEsc": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Allow Escape key to close the popover (default: true)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "close-on-esc",
+                "defaultValue": "true"
+            },
+            "maxHeight": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Maximum height of the popover body. If content exceeds this, it scrolls."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-height",
+                "defaultValue": "'none'"
+            },
+            "interactive": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "When hover trigger is used, allow cursor to move into the popover without closing it.\r\nSet to false for pure tooltip behaviour."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "interactive",
+                "defaultValue": "true"
+            },
+            "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"
+            },
+            "skeleton": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Skeleton state"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "skeleton",
+                "defaultValue": "false"
+            },
+            "offset": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Distance between popover and trigger (in pixels)"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "offset",
+                "defaultValue": "12"
+            },
+            "arrowSize": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Size of the arrow in pixels"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "arrow-size",
+                "defaultValue": "10"
+            },
+            "closeOnOutsideClick": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Close popover when clicking outside"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "close-on-outside-click",
+                "defaultValue": "true"
+            },
+            "closeOnBlur": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Close popover when focus leaves it"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "close-on-blur",
+                "defaultValue": "true"
+            },
+            "matchTriggerWidth": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Match the width of the trigger element"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "match-trigger-width",
+                "defaultValue": "false"
+            },
+            "flip": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enable auto-flipping when hitting screen boundaries"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "flip",
+                "defaultValue": "true"
+            },
+            "shift": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enable auto-shifting (clamping) to stay inside viewport"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "shift",
+                "defaultValue": "true"
+            },
+            "boundary": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'viewport' | 'scrollParent' | HTMLElement",
+                    "resolved": "\"scrollParent\" | \"viewport\" | HTMLElement",
+                    "references": {
+                        "HTMLElement": {
+                            "location": "global",
+                            "id": "global::HTMLElement"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Boundary element for collision detection"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "boundary",
+                "defaultValue": "'viewport'"
+            },
+            "padding": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Padding from boundary edges"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "padding",
+                "defaultValue": "24"
+            },
+            "fallbackPlacements": {
+                "type": "any",
+                "mutable": false,
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Fallback placements for flipping (e.g. \"top, bottom\")"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "fallback-placements"
+            },
+            "autoPlacement": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Automatically choose the best placement based on available space"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "auto-placement",
+                "defaultValue": "false"
+            },
+            "strategy": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'absolute' | 'fixed'",
+                    "resolved": "\"absolute\" | \"fixed\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Positioning strategy"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "strategy",
+                "defaultValue": "'fixed'"
+            },
+            "zIndex": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Optional z-index for the popover panel"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "z-index",
+                "defaultValue": "21000"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "currentPlacement": {},
+            "popoverStyles": {},
+            "arrowStyles": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "uiBeforeOpen",
+                "name": "uiBeforeOpen",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted before popover shows. Call event.preventDefault() to cancel."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "uiOpen",
+                "name": "uiOpen",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when popover shows"
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "uiBeforeClose",
+                "name": "uiBeforeClose",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted before popover hides. Call event.preventDefault() to cancel."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "uiClose",
+                "name": "uiClose",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when popover hides"
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "uiToggle",
+                "name": "uiToggle",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when toggled"
+                },
+                "complexType": {
+                    "original": "{ open: boolean }",
+                    "resolved": "{ open: boolean; }",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "updatePosition": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "HTMLElement": {
+                            "location": "global",
+                            "id": "global::HTMLElement"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "reposition": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "computePlacement": {
+                "complexType": {
+                    "signature": "() => Promise<string>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<string>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "show": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "hide": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            },
+            "toggle": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "element"; }
+    static get watchers() {
+        return [{
+                "propName": "open",
+                "methodName": "visibilityChanged"
+            }, {
+                "propName": "target",
+                "methodName": "handleTriggerConfigChange"
+            }, {
+                "propName": "trigger",
+                "methodName": "handleTriggerConfigChange"
+            }];
+    }
+}