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

/**
 * @cssproperty [--calcite-dialog-scrim-background-color] - Specifies the background color of the component's scrim.
 * @cssproperty [--calcite-dialog-size-x] - When `placement` is `"cover"`, specifies the component's width, using `px`, `em`, `rem`, `vw`, or `%`. Does not exceed the viewport's width.
 * @cssproperty [--calcite-dialog-min-size-x] - Specifies the component's minimum width, using `px`, `em`, `rem`, `vw`, or `%`.
 * @cssproperty [--calcite-dialog-max-size-x] - Specifies the component's maximum width, using `px`, `em`, `rem`, `vw`, or `%`.
 * @cssproperty [--calcite-dialog-size-y] - When `placement` is `"cover"`, specifies the component's height, using `px`, `em`, `rem`, `vh`, or `%`. Does not exceed the viewport's height.
 * @cssproperty [--calcite-dialog-min-size-y] - Specifies the component's minimum height, using `px`, `em`, `rem`, `vh`, or `%`.
 * @cssproperty [--calcite-dialog-max-size-y] - Specifies the component's maximum height, using `px`, `em`, `rem`, `vh`, or `%`.
 * @cssproperty [--calcite-dialog-content-space] - Specifies the padding of the component's content.
 * @cssproperty [--calcite-dialog-footer-space] - Specifies the padding of the component's footer.
 * @cssproperty [--calcite-dialog-border-color] - Specifies the component's border color.
 * @cssproperty [--calcite-dialog-offset-x] - Specifies the component's horizontal offset.
 * @cssproperty [--calcite-dialog-offset-y] - Specifies the component's vertical offset.
 * @cssproperty [--calcite-dialog-background-color] - Specifies the component's background color.
 * @cssproperty [--calcite-dialog-icon-color] - Specifies the color of the component's icon.
 * @cssproperty [--calcite-dialog-accent-color] - When `kind` is specified, specifies the component's accent color.
 * @cssproperty [--calcite-dialog-corner-radius] - Specifies the component's corner radius.
 * @cssproperty [--calcite-dialog-heading-text-color] - Specifies the text color of the component's `heading`.
 * @cssproperty [--calcite-dialog-description-text-color] - Specifies the text color of the component's `description`.
 * @cssproperty [--calcite-dialog-header-background-color] - Specifies the background color of the component's header.
 * @cssproperty [--calcite-dialog-header-action-background-color] - Specifies the background color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s.
 * @cssproperty [--calcite-dialog-header-action-background-color-hover] - Specifies the background color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s when hovered.
 * @cssproperty [--calcite-dialog-header-action-background-color-press] - Specifies the background color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s when pressed.
 * @cssproperty [--calcite-dialog-header-action-text-color] - Specifies the text color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s.
 * @cssproperty [--calcite-dialog-header-action-text-color-press] - Specifies the text color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s when pressed or hovered.
 * @cssproperty [--calcite-dialog-footer-background-color] - Specifies the background color of the component's footer.
 * @cssproperty [--calcite-dialog-space] - Specifies the padding of the component's `unnamed (default)` slot.
 * @cssproperty [--calcite-dialog-header-content-space] - Specifies the padding of the component's `header-content` slot.
 * @cssproperty [--calcite-dialog-action-menu-border-color] - Specifies the border color of the component's internally rendered `calcite-popover`, which is rendered within a `calcite-action` menu when slotted `calcite-action`s are present in the `header-actions-end` slot. Applies to any slotted `calcite-popover`s.
 * @slot  - A slot for adding content.
 * @slot [custom-content] - A slot for displaying custom content. Will prevent the rendering of any default component UI, except for `box-shadow` and `corner-radius`.
 * @slot [action-bar] - A slot for adding a `calcite-action-bar` to the component.
 * @slot [alerts] - A slot for adding `calcite-alert`s to the component.
 * @slot [content-bottom] - A slot for adding content below the unnamed (default) slot and - if populated - the `footer` slot.
 * @slot [content-top] - A slot for adding content above the unnamed (default) slot and - if populated - below the `action-bar` slot.
 * @slot [header-actions-start] - A slot for adding actions or content to the starting side of the component's header.
 * @slot [header-actions-end] - A slot for adding actions or content to the ending side of the component's header.
 * @slot [header-content] - A slot for adding custom content to the component's header.
 * @slot [header-menu-actions] - A slot for adding an overflow menu with actions inside a `calcite-dropdown`.
 * @slot [fab] - A slot for adding a `calcite-fab` (floating action button) to perform an action.
 * @slot [footer] - A slot for adding custom content to the component's footer. Should not be used with the `footer-start` or `footer-end` slots.
 * @slot [footer-end] - A slot for adding a trailing footer custom content. Should not be used with the `footer` slot.
 * @slot [footer-start] - A slot for adding a leading footer custom content. Should not be used with the `footer` slot.
 */
export abstract class Dialog extends LitElement {
  /** Specifies a function to run before the component closes. */
  accessor beforeClose: () => Promise<void>;
  /**
   * When `true`, disables the component's close button.
   *
   * @default false
   */
  accessor closeDisabled: boolean;
  /** Specifies the component's description. */
  accessor description: string;
  /**
   * When `true`, the component is draggable.
   *
   * @default false
   */
  accessor dragEnabled: boolean;
  /**
   * When `true`, disables the default close on escape behavior.
   *
   * By default, an open dialog can be dismissed by pressing the Esc key.
   *
   * @default false
   * @see [Dialog Accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#accessibility).
   */
  accessor escapeDisabled: boolean;
  /**
   * When `true` and `modal` is `false`, 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>;
  /**
   * When `true`, the component will not display at fullscreen, which may be desired in limited display areas, such as mobile devices.
   *
   * @default false
   */
  accessor fullscreenDisabled: boolean;
  /** 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 icon to display. */
  accessor icon: IconName;
  /**
   * When `true` and the element direction is right-to-left (`"rtl"`), flips the component`s `icon`.
   *
   * @default false
   */
  accessor iconFlipRtl: boolean;
  /** Specifies the component's kind, which determines the top border styling. */
  accessor kind: Extract<"brand" | "danger" | "info" | "success" | "warning", Kind>;
  /**
   * When `true`, a busy indicator is displayed.
   *
   * @default false
   */
  accessor loading: boolean;
  /**
   * When `true`, the action menu items in the `header-menu-actions` slot are open.
   *
   * @default false
   */
  accessor menuOpen: boolean;
  /** Overrides individual strings used by the component. */
  accessor messageOverrides: {
      close?: string;
      resizeEnabled?: string;
      dragEnabled?: string;
  };
  /**
   * When `true`, displays a scrim blocking interaction underneath the component.
   *
   * @default false
   */
  accessor modal: boolean;
  /**
   * When `true`, displays and positions the component.
   *
   * @default false
   */
  accessor open: boolean;
  /**
   * When `true`, disables the closing of the component when clicked outside.
   *
   * @default false
   */
  accessor outsideCloseDisabled: 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;
  /**
   * Specifies the component's placement.
   *
   * @default "center"
   */
  accessor placement: DialogPlacement;
  /**
   * When `true`, the component is resizable.
   *
   * @default false
   */
  accessor resizable: boolean;
  /**
   * 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;
  /** 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.
   * @default "m"
   */
  accessor widthScale: Scale;
  /**
   * Scrolls the component's content to a specified set of coordinates.
   *
   * @param options - allows specific coordinates to be defined.
   * @returns promise that resolves once the content is scrolled to.
   * @example
   * myCalciteFlowItem.scrollContentTo({
   *   left: 0, // Specifies the number of pixels along the X axis to scroll the window or element.
   *   top: 0, // Specifies the number of pixels along the Y axis to scroll the window or element
   *   behavior: "auto" // Specifies whether the scrolling should animate smoothly (smooth), or happen instantly in a single jump (auto, the default value).
   * });
   */
  scrollContentTo(options?: ScrollToOptions): Promise<void>;
  /**
   * Sets focus on the component's "close" button (the first focusable item).
   *
   * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component.
   * @returns A promise that is resolved when the operation has completed.
   * @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 focus-trap of the component.
   *
   * @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>;
  /**
   * Updates the component's size by setting its inline and/or block dimensions.
   *
   * Use this method to programmatically override the components's width (inline) and/or height (block).
   * Pass `null` to clear the override and revert to the default or CSS variable size.
   *
   * @param size
   */
  updateSize(size: {
      inline?: number | null;
      block?: number | null;
  }): Promise<void>;
  /** Fires when the component is requested to be closed and before the closing transition begins. */
  readonly calciteDialogBeforeClose: 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 calciteDialogBeforeOpen: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is closed and animation is complete. */
  readonly calciteDialogClose: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component is opened and animation is complete. */
  readonly calciteDialogOpen: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Fires when the component's content is scrolled. */
  readonly calciteDialogScroll: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly "@eventTypes": {
    calciteDialogBeforeClose: Dialog["calciteDialogBeforeClose"]["detail"];
    calciteDialogBeforeOpen: Dialog["calciteDialogBeforeOpen"]["detail"];
    calciteDialogClose: Dialog["calciteDialogClose"]["detail"];
    calciteDialogOpen: Dialog["calciteDialogOpen"]["detail"];
    calciteDialogScroll: Dialog["calciteDialogScroll"]["detail"];
  };
}