@esri/calcite-components/dist/components/calcite-dropdown/customElement.d.ts

Web Components for Esri's Calcite Design System.

/// <reference path="../../index.d.ts" />
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { FlipPlacement, MenuPlacement, OverlayPositioning } from "../../utils/floating-ui.js";
import type { Scale, Width } from "../interfaces.js";
import type { DropdownItem } from "../calcite-dropdown-item/customElement.js";

/**
 * @cssproperty [--calcite-dropdown-width] - Specifies the width of the component's wrapper.
 * @cssproperty [--calcite-dropdown-background-color] - Specifies the component's background color.
 * @slot  - A slot for adding `calcite-dropdown-group` elements. Every `calcite-dropdown-item` must have a parent `calcite-dropdown-group`, even if the `groupTitle` property is not set.
 * @slot [trigger] - A slot for the element that triggers the component.
 */
export abstract class Dropdown extends LitElement {
  /**
   * When `true`, the component will remain open after a selection is made.
   *
   * If the `selectionMode` of the selected `calcite-dropdown-item`'s containing `calcite-dropdown-group` is `"none"`, the component will always close.
   *
   * @default false
   */
  accessor closeOnSelectDisabled: boolean;
  /**
   * When `true`, prevents interaction and decreases the component's opacity.
   *
   * @default false
   */
  accessor disabled: boolean;
  /** Specifies the component's fallback `placement` for slotted `calcite-dropdown-item`s when their initial or specified `placement` has insufficient space available. */
  accessor flipPlacements: FlipPlacement[];
  /**
   * Specifies the maximum number of `calcite-dropdown-item`s to display before showing a scrollbar.
   * Value must be greater than `0`, and does not include `groupTitle`s from `calcite-dropdown-group`.
   *
   * @default 0
   */
  accessor maxItems: number;
  /**
   * Specifies the distance to position the component away from the `referenceElement`.
   *
   * @default 0
   */
  accessor offsetDistance: number;
  /**
   * Specifies the distance to position the component along the `referenceElement`.
   *
   * @default 0
   */
  accessor offsetSkidding: number;
  /**
   * When `true`, displays and positions the component.
   *
   * @default false
   */
  accessor open: boolean;
  /**
   * Specifies the type of positioning to use for overlaid content, where:
   *
   * `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and
   *
   * `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
   *
   * @default "absolute"
   */
  accessor overlayPositioning: OverlayPositioning;
  /**
   * Determines the component's placement relative to the container element.
   *
   * @default "bottom-start"
   */
  accessor placement: MenuPlacement;
  /**
   * Specifies the size of the component.
   *
   * @default "m"
   */
  accessor scale: Scale;
  /** The component's selected items. */
  get selectedItems(): DropdownItem[];
  /**
   * When `true` and the component is `open`, disables top layer placement.
   *
   * Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.
   *
   * @default false
   * @mdn [Top Layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer)
   */
  accessor topLayerDisabled: boolean;
  /**
   * Specifies the type of action on the container element to open the component.
   *
   * @default "click"
   */
  accessor type: "hover" | "click";
  /** Specifies the component's width. */
  accessor width: Extract<Width, Scale>;
  /**
   * Specifies the component's width.
   *
   * @deprecated in v3.0.0, removal target v6.0.0 - Use the `width` property instead.
   */
  accessor widthScale: Scale;
  /**
   * Updates the component's position.
   *
   * @param delayed
   */
  reposition(delayed?: boolean): Promise<void>;
  /**
   * Sets focus on the component's first focusable element.
   *
   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
   * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
   */
  setFocus(options?: FocusOptions): Promise<void>;
  /** Fires when the component is requested to be closed and before the closing transition begins. */
  readonly calciteDropdownBeforeClose: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is added to the DOM but not rendered, and before the opening transition begins. */
  readonly calciteDropdownBeforeOpen: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is closed and animation is complete. */
  readonly calciteDropdownClose: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is opened and animation is complete. */
  readonly calciteDropdownOpen: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when a `calcite-dropdown-item`'s selection changes. */
  readonly calciteDropdownSelect: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly "@eventTypes": {
    calciteDropdownBeforeClose: Dropdown["calciteDropdownBeforeClose"]["detail"];
    calciteDropdownBeforeOpen: Dropdown["calciteDropdownBeforeOpen"]["detail"];
    calciteDropdownClose: Dropdown["calciteDropdownClose"]["detail"];
    calciteDropdownOpen: Dropdown["calciteDropdownOpen"]["detail"];
    calciteDropdownSelect: Dropdown["calciteDropdownSelect"]["detail"];
  };
}