/**
* The `auro-dropdown` element provides a way to place content in a bib that can be toggled.
* @customElement auro-dropdown
*
* @slot - Default slot for the dropdown bib content.
* @slot helpText - Defines the content of the helpText.
* @slot trigger - Defines the content of the trigger.
* @csspart trigger - The trigger content container.
* @csspart wrapper - The trigger wrapper element surrounding the trigger content and chevron.
* @csspart chevron - The collapsed/expanded state icon container.
* @csspart size - The size of the dropdown bib. (height, width, maxHeight, maxWidth only)
* @csspart helpText - The helpText content container.
* @event auroDropdown-triggerClick - Notifies that the trigger has been clicked.
* @event auroDropdown-toggled - Notifies that the visibility of the dropdown bib has changed.
* @event auroDropdown-idAdded - Notifies consumers that the unique ID for the dropdown bib has been generated.
*/
export class AuroDropdown extends AuroElement {
static get shadowRootOptions(): {
clonable?: boolean;
customElementRegistry?: CustomElementRegistry | null;
delegatesFocus?: boolean;
mode: ShadowRootMode;
serializable?: boolean;
slotAssignment?: SlotAssignmentMode;
};
static get properties(): {
/**
* The value for the role attribute of the trigger element.
*/
a11yRole: {
type: StringConstructor;
attribute: boolean;
reflect: boolean;
};
/**
* Defines whether the component will be on lighter or darker backgrounds.
* @type {'default' | 'inverse'}
* @default 'default'
*/
appearance: "default" | "inverse";
/**
* If declared, bib's position will be automatically calculated where to appear.
*/
autoPlacement: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the dropdown will behave as a modal dialog when in a desktop viewport size.
*/
desktopModal: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the dropdown will only show by calling the API .show() public method.
*/
disableEventShow: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, applies a border around the trigger slot.
*/
simple: {
type: BooleanConstructor;
reflect: boolean;
};
/**
* If declared, the dropdown displays a chevron on the right.
*/
chevron: {
type: BooleanConstructor;
reflect: boolean;
attribute: string;
};
/**
* If declared, the dropdown is not interactive.
*/
disabled: {
type: BooleanConstructor;
reflect: boolean;
};
/**
* If declared, the dropdown will not handle keyboard events and will require the consumer to manage this behavior.
*/
disableKeyboardHandling: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* Sets the width of the dropdown bib in pixels.
*/
dropdownWidth: {
type: NumberConstructor;
attribute: string;
};
/**
* The unique ID for the dropdown bib element.
* @private
*/
dropdownId: {
type: StringConstructor;
reflect: boolean;
attribute: boolean;
};
/**
* If declared, will apply error UI to the dropdown.
*/
error: {
type: BooleanConstructor;
reflect: boolean;
};
/**
* Contains the help text message for the current validity error.
*/
errorMessage: {
type: StringConstructor;
attribute: string;
};
/**
* If declared, the bib will display when focus is applied to the trigger.
*/
focusShow: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If true, the dropdown bib is displayed.
*/
isPopoverVisible: {
type: BooleanConstructor;
reflect: boolean;
attribute: string;
};
/**
* If true, the dropdown bib is taking the fullscreen when it's open.
*/
isBibFullscreen: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the trigger will toggle the dropdown on mouseover/mouseout.
*/
hoverToggle: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* @private
*/
hasTriggerContent: {
type: BooleanConstructor;
attribute: boolean;
};
/**
* Defines the screen size breakpoint at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.
*
* When expanded, the dropdown will automatically display in fullscreen mode
* if the screen size is equal to or smaller than the selected breakpoint.
* @type {'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'disabled'}
* @default 'sm'
*/
fullscreenBreakpoint: "xs" | "sm" | "md" | "lg" | "xl" | "disabled";
/**
* Sets the layout of the dropdown.
* @type {'classic' | 'emphasized' | 'snowflake'}
* @default 'classic'
*/
layout: "classic" | "emphasized" | "snowflake";
/**
* Sets the shape of the dropdown.
* @type {'box' | 'classic' | 'pill' | 'pill-left' | 'pill-right' | 'rounded' | 'snowflake'}
*/
shape: "box" | "classic" | "pill" | "pill-left" | "pill-right" | "rounded" | "snowflake";
/**
* Sets the size of the dropdown.
* @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
*/
size: "xs" | "sm" | "md" | "lg" | "xl";
/**
* Defines if the trigger should size based on the parent element providing the border UI.
* @private
*/
parentBorder: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the popover and trigger will be set to the same width.
*/
matchWidth: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the bib will NOT flip to an alternate position
* when there isn't enough space in the specified `placement`.
*/
noFlip: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the dropdown will shift its position to avoid being cut off by the viewport.
*/
shift: {
type: BooleanConstructor;
reflect: boolean;
};
/**
* If declared, the dropdown will not hide when moving focus outside the element.
*/
noHideOnThisFocusLoss: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, the trigger will only show the dropdown bib.
*/
noToggle: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* Gap between the trigger element and bib.
* @default 0
*/
offset: {
type: NumberConstructor;
reflect: boolean;
};
/**
* DEPRECATED - use `appearance="inverse"` instead.
* @deprecated Use `appearance="inverse"` instead.
*/
onDark: {
type: BooleanConstructor;
attribute: string;
reflect: boolean;
};
/**
* If declared, and a function is set, that function will execute when the slot content is updated.
* @type {() => void}
*/
onSlotChange: () => void;
/**
* Position where the bib should appear relative to the trigger.
* @type {'top' | 'right' | 'bottom' | 'left' | 'bottom-start' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-end' | 'left-start' | 'left-end'}
* @default 'bottom-start'
*/
placement: "top" | "right" | "bottom" | "left" | "bottom-start" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-end" | "left-start" | "left-end";
/**
* Sets the tabindex applied to the dropdown trigger for keyboard focus order.
*/
tabIndex: {
type: NumberConstructor;
attribute: string;
};
/**
* Accessible label for the dropdown bib dialog element.
* @private
*/
bibDialogLabel: {
type: StringConstructor;
attribute: boolean;
reflect: boolean;
};
};
static get styles(): import("lit").CSSResult[];
/**
* This will register this element with the browser.
* @param {string} [name="auro-dropdown"] - The name of the element that you want to register.
*
* @example
* AuroDropdown.register("custom-dropdown") // this will register this element to
*
*/
static register(name?: string): void;
isPopoverVisible: boolean;
isBibFullscreen: boolean;
matchWidth: boolean;
noHideOnThisFocusLoss: boolean;
/**
* When true, the dropdown skips its generic focus restoration on close.
* Set by consumers (for example combobox) that manage their own focus routing
* via setClearBtnFocus / setInputFocus / keyboard strategy.
* Separate from noHideOnThisFocusLoss (which controls auto-close behavior).
* @private
*/
private noFocusRestoreOnClose;
errorMessage: any;
layout: any;
shape: any;
size: any;
parentBorder: boolean;
/**
* Handles the custom event `auroDropdown-toggled` to update the visibility of the dropdown bib.
* @private
* @param {CustomEvent} event - The custom event that contains the dropdown toggle information.
*/
private handleDropdownToggle;
/** @private */
private bibElement;
/**
* @private
* @returns {object} Class definition for the wrapper element.
*/
private get commonWrapperClasses();
/**
* @private
* @returns {void} Internal defaults.
*/
private _intializeDefaults;
appearance: string | undefined;
chevron: boolean | undefined;
desktopModal: boolean | undefined;
disabled: boolean | undefined;
disableKeyboardHandling: boolean | undefined;
error: boolean | undefined;
noToggle: boolean | undefined;
a11yRole: string | undefined;
onDark: boolean | undefined;
showTriggerBorders: boolean | undefined;
triggerContentFocusable: any;
simple: boolean | undefined;
placement: string | undefined;
offset: number | undefined;
noFlip: boolean | undefined;
shift: boolean | undefined;
autoPlacement: boolean | undefined;
/**
* @private
*/
private hasTriggerContent;
/**
* @private
*/
private triggerContentSlot;
/**
* @private
*/
private runtimeUtils;
/**
* @private
*/
private floater;
/**
* @private
*/
private iconTag;
/**
* @private
*/
private dropdownBibTag;
/**
* @private
*/
private helpTextTag;
/**
* Creates and dispatches a duplicate focus event on the trigger element.
* @private
* @param {Event} event - The original focus event.
*/
private bindFocusEventToTrigger;
/**
* @ignore
*/
get floaterConfig(): {
placement: string | undefined;
flip: boolean;
shift: boolean | undefined;
autoPlacement: boolean | undefined;
offset: number | undefined;
};
/**
* Public method to hide the dropdown.
* @returns {void}
*/
hide(): void;
/**
* Public method to show the dropdown.
* @returns {void}
*/
show(): void;
/**
* When bib is open, focus on the first element inside of bib.
* If not, trigger element will get focus.
*/
focus(): void;
/**
* Focus the trigger content. When the trigger wrapper itself is focusable
* (has tabindex), focus it directly. Otherwise, focus the first focusable
* element slotted into the trigger slot (for example the auro-input).
* @private
*/
private focusTrigger;
/**
* Sets the active descendant element for accessibility.
* Uses ariaActiveDescendantElement to cross shadow DOM boundaries.
* This function is used in components that contain `auro-dropdown` to set the active descendant.
* @private
* @param {HTMLElement|null} element - The element to set as the active descendant, or null to clear.
* @returns {void}
*/
private setActiveDescendant;
/**
* Accessor for reusing the focusable entity query string.
* @private
* @returns {string}
*/
private get focusableEntityQuery();
_bibTabHandler: ((event: any) => void) | undefined;
focusTrap: any;
updated(changedProperties: any): void;
firstUpdated(): void;
dropdownId: any;
bibContent: any;
/**
* Exposes CSS parts for styling from parent components.
* @returns {void}
*/
exposeCssParts(): void;
/**
* Determines if content is within a custom slot.
* @private
* @param {HTMLElement} element - The element to check.
* @returns {Boolean}
*/
private isCustomSlotContent;
/**
* Function to support @focusin event.
* @private
* @return {void}
*/
private handleFocusin;
hasFocus: boolean | undefined;
/**
* @private
*/
private updateFocusTrap;
_noHideOverridden: boolean | undefined;
_priorNoHide: any;
_priorNoHideOnFocusLoss: boolean | undefined;
/**
* Returns the chain of active (focused) elements through shadow roots.
* @private
* @returns {Array}
*/
private _getActiveElements;
/**
* Sets `inert` on sibling elements of the dropdown's top-level host
* so that content outside the dropdown is not interactive while the modal is open.
* Walks up through shadow DOM boundaries to find the outermost host element
* in the light DOM, then sets `inert` on siblings at each ancestor level
* to ensure all page content outside the host subtree is inert.
* @private
*/
private _setPageInert;
_inertSiblings: any[] | undefined;
/**
* Restores `inert` state on siblings that were tracked by `_setPageInert`.
* Uses reference counting so inert is only cleared when the last modal
* dropdown releases a given element. Preserves the original inert state
* so externally-inerted elements are not inadvertently re-enabled.
* @private
*/
private _clearPageInert;
/**
* Function to support @focusout event.
* @private
* @return {void}
*/
private handleFocusout;
/**
* Sets up event listeners to deliver focus and blur events from nested Auro components within the trigger slot to trigger.
* This ensures that focus/blur events originating from within these components are propagated to the trigger element itself.
* @private
*/
private setupTriggerFocusEventBinding;
/**
* Clears focus and blur event listeners from nested Auro components within the trigger slot.
* @private
* @returns {void}
*/
private clearTriggerFocusEventBinding;
clearTriggerA11yAttributes(triggerElement: any): void;
/**
* Handles changes to the trigger content slot and updates related properties.
*
* It first updates the floater settings
* Then, it retrieves the assigned nodes from the event target and checks if any of
* the nodes contain non-empty text content, updating the `hasTriggerContent` property accordingly.
*
* @private
* @method handleTriggerContentSlotChange
* @param {Event} event - Native slotchange event.
* @returns {void}
*/
private handleTriggerContentSlotChange;
triggerNode: EventTarget | null | undefined;
/**
* Handles the default slot change event and updates the content.
*
* This method retrieves all nodes assigned to the default slot of the event target and appends them
* to the `bibContent` element. If a callback function `onSlotChange` is defined, it is invoked to
* notify about the slot change.
*
* @private
* @method handleDefaultSlot
* @fires Function#onSlotChange - Optional callback invoked when the slot content changes.
*/
private handleDefaultSlot;
/**
* Returns HTML for the common portion of the layouts.
* @private
* @param {Object} helpTextClasses - Classes to apply to the help text container.
* @returns {html} - Returns HTML.
*/
private renderBasicHtml;
/**
* Returns HTML for the classic layout. Does not support type="*".
* @private
* @returns {html} - Returns HTML for the classic layout.
*/
private renderLayoutClassic;
/**
* Returns HTML for the snowflake layout. Does not support type="*".
* @private
* @returns {html} - Returns HTML for the snowflake layout.
*/
private renderLayoutSnowflake;
/**
* Returns HTML for the emphasized layout. Does not support type="*".
* @private
* @returns {html} - Returns HTML for the emphasized layout.
*/
private renderLayoutEmphasized;
/**
* Logic to determine the layout of the component.
* @private
* @param {string} [ForcedLayout] - Used to force a specific layout, pass in the layout name to use.
* @returns {HTMLCollection} - Returns the HTML for the layout.
*/
private renderLayout;
}
import { AuroElement } from '../../layoutElement/src/auroElement.js';