@momentum-ui/web-components 2.22.17 → 2.23.1

package/dist/types/components/popover/Popover.d.ts

@@ -8,199 +8,302 @@
 import "@/components/button/Button";
 import "@/components/icon/Icon";
 import { LitElement, PropertyValues } from "lit-element";
-import { PlacementType, PopoverRoleType, StrategyType } from "./Popover.types";
-export declare namespace Popover {
-    const ELEMENT_base: typeof LitElement & import("@/mixins/FocusTrapMixin").AnyConstructor<import("@/mixins/FocusTrapMixin").FocusTrapClass & import("@/mixins/FocusTrapMixin").FocusTrapInterface & import("../../mixins/FocusMixin").FocusClass>;
-    /**
-     * @fires popover-open-changed - Fired when the popover is opened or closed.
-     */
-    export class ELEMENT extends ELEMENT_base {
-        /**
-         * The placement of the popover relative to the trigger element.
-         *
-         * This property specifies where the popover should appear in relation to the trigger element.
-         * The default placement is "bottom", but it can be customized to other positions such as "top", "left", or "right".
-         *
-         * @type {PlacementType}
-         */
-        placement: PlacementType;
-        /**
-         * The positioning strategy for the popover.
-         *
-         * This property specifies how the popover is positioned relative to the trigger element.
-         * It accepts two values:
-         * - `"absolute"`: The popover is positioned relative to the nearest positioned ancestor.
-         * - `"fixed"`: The popover is positioned relative to the viewport, allowing it to escape parent containers with `overflow: hidden` or `overflow: auto`.
-         *
-         * By default, the positioning strategy is `"absolute"`. Use `"fixed"` if the popover needs to escape parent boundaries.
-         *
-         * @type {StrategyType}
-         */
-        positioningStrategy?: StrategyType;
-        /**
-         * Indicates whether the popover is open.
-         *
-         * This property controls the visibility of the popover. When set to true, the popover is displayed.
-         * When set to false, the popover is hidden.
-         *
-         * @type {boolean}
-         */
-        isOpen: boolean;
-        /**
-         * Indicates whether the arrow should be shown on the popover.
-         *
-         * This property controls the visibility of the arrow on the popover. When set to true, the arrow is displayed.
-         * When set to false, the arrow is hidden.
-         *
-         * @type {boolean}
-         */
-        showArrow: boolean;
-        /**
-         * Indicates whether the close button should be shown on the popover.
-         *
-         * This property controls the visibility of the close button on the popover. When set to true, the close button is displayed.
-         * When set to false, the close button is hidden.
-         *
-         * @type {boolean}
-         */
-        showClose?: boolean | undefined;
-        /**
-         * Indicates whether the popover is interactive.
-         *
-         * When set to true, the popover will allow user interactions within it.
-         * This property is used to determine if the popover should trap focus.
-         *
-         * @type {boolean}
-         */
-        interactive: boolean;
-        /**
-         * The role attribute for the popover.
-         *
-         * This property specifies the `role` attribute for the popover, which defines its role in the accessibility tree.
-         * The default role is "dialog", but it can be customized to "dialog", "menu" or "tooltip.
-         *
-         * @type {PopoverRoleType}
-         */
-        role: PopoverRoleType;
-        /**
-         * The accessible label for the popover.
-         *
-         * This property specifies the `aria-label` attribute for the popover, which provides an accessible name for the popover element.
-         * It is used by screen readers to announce the purpose of the popover to users with visual impairments.
-         *
-         * @type {string | null}
-         */
-        ariaLabel: string | null;
-        /**
-         * The offset distance (in pixels) from the trigger element.
-         *
-         * This property specifies the distance between the trigger element and the popover.
-         * It is used to control the spacing between the trigger element and the popover when the popover is displayed.
-         *
-         * @type {number}
-         */
-        offsetDistance: number;
-        /**
-         * The slot element that contains the trigger element for the popover.
-         *
-         * This property is used to query the slot with the name "triggerElement" and store a reference to it.
-         * The trigger element is the element that, when interacted with, will open or close the popover.
-         *
-         * @type {HTMLSlotElement}
-         */
-        triggerSlot: HTMLSlotElement;
-        /**
-         * The popover container element.
-         *
-         * This property is used to query the popover container element in the DOM.
-         * The popover container is the main element that contains the popover content.
-         *
-         * @type {HTMLDivElement}
-         */
-        popoverContainer: HTMLDivElement;
-        /**
-         * The popover arrow element.
-         *
-         * This property is used to query the popover arrow element in the DOM.
-         * The popover arrow is the element that visually connects the popover to the trigger element.
-         *
-         * @type {HTMLDivElement}
-         */
-        popoverArrow: HTMLDivElement;
-        /**
-         * The event that triggers the popover.
-         *
-         * This property specifies the event that will trigger the popover to open or close.
-         * The default event is "click", but it can be customized to other events such as "mouseenter" or "focus".
-         *
-         * @type {string}
-         */
-        trigger?: string;
-        /**
-         * Indicates whether the popover should use an inverted color scheme.
-         *
-         * When set to `true`, the popover will invert its background color and text color.
-         *
-         * @type {boolean}
-         */
-        inverted: boolean;
-        /**
-         * The trigger element for the popover.
-         *
-         * This property holds a reference to the trigger element that, when interacted with, will open or close the popover.
-         *
-         * @type {HTMLElement | null}
-         */
-        private triggerElement;
-        /**
-         * The Popper.js instance used to manage the positioning of the popover.
-         *
-         * This instance is created when the popover is opened and destroyed when the popover is closed.
-         * It is used to handle the positioning and alignment of the popover relative to the trigger element.
-         */
-        private popperInstance;
-        /**
-         * If mouse is over the trigger element or popover container.
-         *
-         * This property is used when both focus and mouse triggers are present
-         * When focus leaves the trigger element if mouse is hovering we should not close the popover
-         */
-        private isMouseOver;
-        static get styles(): import("lit-element").CSSResult[];
-        connectedCallback(): void;
-        disconnectedCallback(): void;
-        private setupTriggerEvents;
-        onOutsideOverlayClick: (event: MouseEvent) => void;
-        onWindowBlurEvent: () => void;
-        onOutsideOverlayKeydown: (event: KeyboardEvent) => Promise<void>;
-        private handleTriggerElementSlotChange;
-        private onContentSlotChanged;
-        onTriggerElementClicked: () => void;
-        onTriggerElementKeydown: (event: KeyboardEvent) => Promise<void>;
-        onFocusInTrigger: () => void;
-        onFocusOutTrigger: () => void;
-        onMouseEnteredTriggerOrPopup: (_event: MouseEvent) => void;
-        onMouseLeaveTriggerOrPopup: (_event: MouseEvent) => void;
-        private shouldStayOpenOnTriggerFocus;
-        private readonly setIsOpenDebounced;
-        protected firstUpdated(changedProperties: PropertyValues): void;
-        private focusInsideOverlay;
-        private focusOnTrigger;
-        private toggleOverlay;
-        private handleCreatePopperFirstUpdate;
-        private createInstance;
-        private destroyInstance;
-        protected updated(changedProperties: PropertyValues): void;
-        private isOpenUpdated;
-        private dispatchPopoverIsOpenChanged;
-        private get popoverClassMap();
-        private get renderPopoverTemplate();
-        render(): import("lit-element").TemplateResult;
-    }
-    export {};
+import { PopoverColor, PopoverPlacement, PopoverStrategy, PopoverTrigger } from "./Popover.types";
+declare const Popover_base: typeof LitElement & import("@/mixins/FocusTrapMixin").AnyConstructor<import("@/mixins/FocusTrapMixin").FocusTrapClass & import("@/mixins/FocusTrapMixin").FocusTrapInterface & import("../../mixins/FocusMixin").FocusClass>;
+/**
+ * Popover component is a lightweight floating UI element that displays additional content when triggered.
+ * It can be used for tooltips, dropdowns, or contextual menus.
+ * The popover automatically positions itself based on available space and
+ * supports dynamic height adjustments with scrollable content when needed。
+ *
+ * @dependency md-button
+ * @dependency md-icon
+ *
+ * @tagname md-popover
+ *
+ * @event shown - This event is dispatched when the popover is shown
+ * @event hidden - This event is dispatched when the popover is hidden
+ * @event created - This event is dispatched when the popover is created (added to the DOM)
+ * @event destroyed - This event is dispatched when the popover is destroyed (removed from the DOM)
+ *
+ * @cssproperty --md-popover-arrow-border-radius - radius of the arrow border
+ * @cssproperty --md-popover-arrow-border - border of the arrow
+ * @cssproperty --popover-bg-color - primary background color of the popover
+ * @cssproperty --popover-border-color - border color of the popover
+ * @cssproperty --popover-text-color - text color of the popover
+ * @cssproperty --popover-inverted-bg-color - inverted background color of the popover
+ * @cssproperty --popover-inverted-border-color - inverted border color of the popover
+ * @cssproperty --popover-inverted-text-color - inverted text color of the popover
+ * @cssproperty --md-popover-elevation-3 - elevation of the popover
+ * @cssproperty --md-popover-max-width - max width of the popover
+ * @cssproperty --md-popover-max-height - max height of the popover
+ *
+ * @slot - Default slot for the popover content
+ *
+ */
+export declare class Popover extends Popover_base {
+    /**
+     * The unique ID of the popover.
+     */
+    id: string;
+    /**
+     * The ID of the element that triggers the popover.
+     * This attribute is required for the popover to work.
+     */
+    triggerID: string;
+    /**
+     * Determines the events that cause the Popover to show.
+     * Multiple event names should be separated by spaces.
+     * For example to allow both click and hover, use 'click mouseenter' as the trigger.
+     * - **click**
+     * - **mouseenter**
+     * - **focusin**
+     * - **manual**
+     * @default click
+     */
+    trigger: PopoverTrigger;
+    /**
+     * The placement of the popover.
+     * - **top**
+     * - **top-start**
+     * - **top-end**
+     * - **bottom**
+     * - **bottom-start**
+     * - **bottom-end**
+     * - **left**
+     * - **left-start**
+     * - **left-end**
+     * - **right**
+     * - **right-start**
+     * - **right-end**
+     * @default bottom
+     */
+    placement: PopoverPlacement;
+    /**
+     * The positioning strategy for the popover.
+     * - **absolute** - Position relative to closest positioned ancestor or the document body
+     * - **fixed** - Position relative to the viewport
+     * @default absolute
+     */
+    strategy: PopoverStrategy;
+    /**
+     * Color of the popover
+     * - **tonal**
+     * - **contrast**
+     * @default tonal
+     */
+    color: PopoverColor;
+    /**
+     * The visibility of the popover.
+     * @default false
+     */
+    visible: boolean;
+    /**
+     * The offset of the popover.
+     * @default 4
+     */
+    offset: number;
+    /**
+     * Determines whether the focus trap is enabled.
+     * If true, focus will be restricted to the content within this component.
+     * @default false
+     */
+    focusTrap: boolean;
+    /**
+     * Prevent outside scrolling when popover show.
+     * @default false
+     */
+    preventScroll: boolean;
+    /**
+     * The arrow visibility of the popover.
+     * @default false
+     */
+    showArrow: boolean;
+    /**
+     * The close button visibility of the popover.
+     * @default false
+     */
+    closeButton: boolean;
+    /**
+     * Determines whether the popover is interactive。
+     * @default false
+     */
+    interactive: boolean;
+    /**
+     * The delay of the show/hide popover.
+     * @default 0,0
+     */
+    delay: string;
+    /**
+     * Hide popover on escape key press.
+     * @default false
+     */
+    hideOnEscape: boolean;
+    /**
+     * Hide popover on blur.
+     * @default false
+     */
+    hideOnBlur: boolean;
+    /**
+     * Hide on outside click of the popover.
+     * @default false
+     */
+    hideOnOutsideClick: boolean;
+    /**
+     * The focus back to trigger after the popover hide.
+     * @default false
+     */
+    focusBackToTrigger: boolean;
+    /**
+     * Determines whether the popover with backdrop.
+     * Other than popover and trigger element, the rest of the screen will be covered with a backdrop.
+     * @default false
+     */
+    backdrop: boolean;
+    /**
+     * Changes the placement of popover to keep it in view when scrolling.
+     * @default true
+     */
+    flip: boolean;
+    /**
+     * Changes the size of popover to keep it in view when scrolling.
+     * @default false
+     */
+    size: boolean;
+    /**
+     * The z-index of the popover.
+     * @default 1000
+     */
+    zIndex: number;
+    /**
+     * Element ID that the popover append to.
+     * @default ''
+     */
+    appendTo: string;
+    /**
+     * aria-label attribute to be set for close button accessibility.
+     * @default null
+     */
+    closeButtonAriaLabel: string | null;
+    /**
+     * Role of the popover
+     * @default dialog
+     */
+    role: HTMLElement["role"];
+    /**
+     * aria-labelledby for an interactive popover only, defaults to the trigger component id.
+     * Used in nested cases where the triggerComponent isn't the actual button.
+     */
+    ariaLabelledby: string | null;
+    /**
+     * aria-describedby of the popover.
+     */
+    ariaDescribedby: string | null;
+    /**
+     * Disable aria-expanded attribute on trigger element.
+     * Make sure to set this to false when the popover is interactive.
+     * @default false
+     */
+    disableAriaExpanded: boolean;
+    arrowElement: HTMLElement | null;
+    triggerElement: HTMLElement | null;
+    /** @internal */
+    private hoverTimer;
+    /** @internal */
+    private isTriggerClicked;
+    /** @internal */
+    private openDelay;
+    /** @internal */
+    private closeDelay;
+    /** @internal */
+    private readonly utils;
+    /** @internal */
+    backdropElement: HTMLElement | null;
+    useLegacyFindFocusable: () => boolean;
+    constructor();
+    protected firstUpdated(changedProperties: PropertyValues): Promise<void>;
+    disconnectedCallback(): Promise<void>;
+    /**
+     * Sets up the trigger event listeners based on the trigger type.
+     */
+    setupTriggerListener(): void;
+    /**
+     * Removes the trigger event listeners.
+     */
+    removeEventListeners(): void;
+    protected updated(changedProperties: PropertyValues): Promise<void>;
+    /**
+     * Handles the outside click event to close the popover.
+     * Uses event.composedPath() to handle clicks across Shadow DOM boundaries.
+     *
+     * @param event - The mouse event.
+     */
+    private readonly onOutsidePopoverClick;
+    /**
+     * Handles the escape keydown event to close the popover.
+     *
+     * @param event - The keyboard event.
+     */
+    private readonly onEscapeKeydown;
+    /**
+     * Handles the popover focus out event.
+     *
+     * @param event - The focus event.
+     */
+    private readonly onPopoverFocusOut;
+    /**
+     * Handles the popover visibility change and position the popover.
+     * Handles the exit event to close the popover.
+     *
+     * @param oldValue - The old value of the visible property.
+     * @param newValue - The new value of the visible property.
+     */
+    private isOpenUpdated;
+    /**
+     * Starts the close delay timer.
+     * If the popover is not interactive, it will close the popover after the delay.
+     */
+    private readonly startCloseDelay;
+    /**
+     * Cancels the close delay timer.
+     */
+    readonly cancelCloseDelay: () => void;
+    /**
+     * Shows the popover.
+     * By default (`useOpenDelay = false`), or if `openDelay` is 0 or less, the popover opens immediately.
+     * If `useOpenDelay` is true and `openDelay` is greater than 0, the `openDelay` will be applied before showing the popover.
+     * This allows programmatic calls (e.g., for `trigger="manual"`) to optionally use the `openDelay`.
+     * @param {boolean} [useOpenDelay=false] - Indicates if the `openDelay` should be applied.
+     */
+    showPopover: (useOpenDelay?: boolean) => void;
+    /**
+     * Hides the popover.
+     */
+    hidePopover: () => void;
+    /**
+     * Toggles the popover visibility.
+     */
+    togglePopoverVisible: () => void;
+    private readonly onMouseEnterTrigger;
+    private readonly onFocusInTrigger;
+    private readonly onTriggerClick;
+    private isMouseOverTrigger;
+    /**
+     * Sets the focusable elements inside the popover.
+     */
+    private handleCreatePopoverFirstUpdate;
+    /**
+     * Positions the popover based on the trigger element.
+     * It also handles the flip, size and arrow placement.
+     * It uses the floating-ui/dom library to calculate the position.
+     */
+    private positionPopover;
+    render(): import("lit-element").TemplateResult;
+    static get styles(): import("lit-element").CSSResult[];
 }
 declare global {
     interface HTMLElementTagNameMap {
-        "md-popover": Popover.ELEMENT;
+        "md-popover": Popover;
     }
 }
+export {};

package/dist/types/components/popover/Popover.events.d.ts

@@ -0,0 +1,34 @@
+import { type Popover } from "./Popover";
+export declare class PopoverEventManager {
+    /**
+     * Dispatches a custom event for the popover.
+     *
+     * @param eventName - The name of the event.
+     * @param instance - The popover instance.
+     */
+    static dispatchPopoverEvent(eventName: string, instance: Popover): void;
+    /**
+     * Custom event that is fired when the popover is shown.
+     *
+     * @param instance - The popover instance.
+     */
+    static onShowPopover(instance: Popover): void;
+    /**
+     * Custom event that is fired when the popover is hidden.
+     *
+     * @param instance - The popover instance.
+     */
+    static onHidePopover(instance: Popover): void;
+    /**
+     * Custom event that is fired when the popover is created.
+     *
+     * @param instance - The popover instance.
+     */
+    static onCreatedPopover(instance: Popover): void;
+    /**
+     * Custom event that is fired when the popover is destroyed.
+     *
+     * @param instance - The popover instance.
+     */
+    static onDestroyedPopover(instance: Popover): void;
+}

package/dist/types/components/popover/Popover.stack.d.ts

@@ -0,0 +1,45 @@
+import { type Popover } from "./Popover";
+/**
+ * Manages a stack of popovers to control their order and lifecycle.
+ * This class allows adding, removing, and retrieving popovers
+ * while maintaining their stacking behavior.
+ *
+ */
+declare class PopoverStack {
+    /**
+     * Stack to maintain the order of popovers
+     * @internal
+     */
+    private stack;
+    /**
+     * Adds a popover to the stack
+     *
+     * @param popover - Popover instance
+     */
+    push(popover: Popover): void;
+    /**
+     * Removes the last popover from the stack
+     *
+     * @returns The last popover in the stack
+     */
+    pop(): Popover | undefined;
+    /**
+     * Returns the last popover in the stack
+     * without removing it
+     *
+     * @returns The last popover in the stack
+     */
+    peek(): Popover | undefined;
+    /**
+     * Removes a popover from the stack
+     *
+     * @param popover - Popover instance
+     */
+    remove(popover: Popover): void;
+    /**
+     * Clears the stack
+     */
+    clear(): void;
+}
+export declare const popoverStack: PopoverStack;
+export {};

package/dist/types/components/popover/Popover.types.d.ts

@@ -1,8 +1,20 @@
+import { COLOR, POPOVER_PLACEMENT, POPOVER_STRATEGY, TRIGGER } from "./Popover.constants";
+export type ValueOf<T> = T[keyof T];
+type PopoverPlacement = ValueOf<typeof POPOVER_PLACEMENT>;
+type PopoverColor = ValueOf<typeof COLOR>;
+type PopoverTrigger = ValueOf<typeof TRIGGER> | `${ValueOf<typeof TRIGGER>} ${ValueOf<typeof TRIGGER>}`;
+type PopoverStrategy = ValueOf<typeof POPOVER_STRATEGY>;
 export declare const Placement: readonly ["auto", "auto-start", "auto-end", "left-start", "left", "left-end", "right-start", "right", "right-end", "top-start", "top", "top-end", "bottom-start", "bottom", "bottom-end"];
-export declare const ARROW_HEIGHT = 16;
+interface Events {
+    onShownEvent: Event;
+    onHiddenEvent: Event;
+    onCreatedEvent: Event;
+    onDestroyedEvent: Event;
+}
 export declare const Strategy: readonly ["fixed", "absolute"];
 export declare const PopoverRole: readonly ["dialog", "menu", "tooltip"];
 export declare const Triggers: readonly ["click", "mouseenter", "manual"];
 export type PlacementType = (typeof Placement)[number];
 export type StrategyType = (typeof Strategy)[number];
 export type PopoverRoleType = (typeof PopoverRole)[number];
+export type { Events, PopoverColor, PopoverPlacement, PopoverStrategy, PopoverTrigger };