@esri/calcite-components/dist/components/calcite-popover/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, LogicalPlacement, OverlayPositioning, ReferenceElement } from "../../utils/floating-ui.js";
import type { HeadingLevel } from "../functional/Heading.js";
import type { Scale } from "../interfaces.js";
import type { FocusTrapOptions } from "../../controllers/useFocusTrap.js";

/**
 * @cssproperty [--calcite-popover-background-color] - Specifies the component's background color.
 * @cssproperty [--calcite-popover-border-color] - Specifies the component's border color.
 * @cssproperty [--calcite-popover-corner-radius] - Specifies the component's corner radius.
 * @cssproperty [--calcite-popover-max-size-x] - Specifies the component's maximum width.
 * @cssproperty [--calcite-popover-text-color] - Specifies the component's text color.
 * @slot  - A slot for adding custom content.
 */
export abstract class Popover extends LitElement {
  /**
   * When `true`, clicking outside of the component automatically closes open `calcite-popover`s.
   *
   * @default false
   */
  accessor autoClose: boolean;
  /**
   * When `true`, displays a close button in the component.
   *
   * @default false
   */
  accessor closable: boolean;
  /**
   * When `true`, prevents flipping the component's placement when overlapping its `referenceElement`.
   *
   * @default false
   */
  accessor flipDisabled: boolean;
  /** Specifies the component's fallback `placement` for slotted content when it's initial or specified `placement` has insufficient space available. */
  accessor flipPlacements: FlipPlacement[];
  /**
   * When `true`, prevents focus trapping.
   *
   * @default false
   */
  accessor focusTrapDisabled: boolean;
  /**
   * Specifies custom focus trap configuration on the component, where
   *
   * `"allowOutsideClick`" allows outside clicks,
   * `"initialFocus"` enables initial focus,
   * `"returnFocusOnDeactivate"` returns focus when not active,
   * `"extraContainers"` specifies additional focusable elements external to the trap, such as 3rd-party components appending elements to the document body, and
   * `"setReturnFocus"` customizes the element to which focus is returned when the trap is deactivated. Return `false` to prevent focus return, or `undefined` to use the default behavior (returning focus to the element focused before activation).
   */
  accessor focusTrapOptions: Partial<FocusTrapOptions>;
  /** Specifies the component's heading text. */
  accessor heading: string;
  /** Specifies the heading level number of the component's `heading` for proper document structure, without affecting visual styling. */
  accessor headingLevel: HeadingLevel;
  /**
   * Specifies an accessible label for the component.
   *
   * @required
   */
  accessor label: string;
  /** Overrides individual strings used by the component. */
  accessor messageOverrides: { close?: string; };
  /** Specifies the distance to position the component away from the `referenceElement`. */
  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 where the component will be positioned relative to the `referenceElement`.
   *
   * @default "auto"
   */
  accessor placement: LogicalPlacement;
  /**
   * When `true`, removes the caret pointer.
   *
   * @default false
   */
  accessor pointerDisabled: boolean;
  /**
   * The `referenceElement` is used to position the component according to its `placement` value.
   *
   * Setting the value to an `HTMLElement` is preferred so the component does not need to query the DOM.
   *
   * However, a string `id` of the reference element can also be used.
   *
   * The component should not be placed within its own `referenceElement` to avoid unintended behavior.
   *
   * @required
   */
  accessor referenceElement: ReferenceElement | string;
  /**
   * Specifies the size of the component.
   *
   * @default "m"
   */
  accessor scale: Scale;
  /**
   * 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;
  /**
   * When `true`, disables automatically toggling the component when its `referenceElement` has been triggered.
   *
   * This property can be set to `true` to manage when the component is open.
   *
   * @default false
   */
  accessor triggerDisabled: boolean;
  /**
   * Updates the position of the component.
   *
   * @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>;
  /**
   * Updates the element(s) that are included in the component's focus-trap.
   *
   * @param extraContainers - Additional elements to include in the focus trap. This is useful for including elements that may have related parts rendered outside the main focus trapping element.
   */
  updateFocusTrapElements(extraContainers?: FocusTrapOptions["extraContainers"]): Promise<void>;
  /** Fires when the component is requested to be closed and before the closing transition begins. */
  readonly calcitePopoverBeforeClose: 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 calcitePopoverBeforeOpen: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is closed and animation is complete. */
  readonly calcitePopoverClose: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is open and animation is complete. */
  readonly calcitePopoverOpen: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly "@eventTypes": {
    calcitePopoverBeforeClose: Popover["calcitePopoverBeforeClose"]["detail"];
    calcitePopoverBeforeOpen: Popover["calcitePopoverBeforeOpen"]["detail"];
    calcitePopoverClose: Popover["calcitePopoverClose"]["detail"];
    calcitePopoverOpen: Popover["calcitePopoverOpen"]["detail"];
  };
}