@esri/calcite-components 5.0.0-next.9 → 5.0.0

package/dist/components/calcite-dialog/customElement.d.ts

@@ -1,16 +1,43 @@
 /// <reference path="../../index.d.ts" />
-import { PropertyValues } from 'lit';
-import { JsxNode, PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
-import { Kind, Scale, Width } from '../interfaces';
-import { HeadingLevel } from '../functional/Heading';
-import { OverlayPositioning } from '../../utils/floating-ui';
-import { FocusTrapOptions } from '../../controllers/useFocusTrap';
-import { IconName } from '../calcite-icon/interfaces';
-import { DialogPlacement } from './interfaces';
+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 Dialog UI, except for `box-shadow` and `corner-radius`.
+ * @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.
@@ -20,180 +47,208 @@ import { DialogPlacement } from './interfaces';
  * @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.
+ * @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 declare class Dialog extends LitElement {
-    /** Passes a function to run before the component closes. */
-    beforeClose: () => Promise<void>;
-    /**
-     * When `true`, disables the component's close button.
-     *
-     * @default false
-     */
-    closeDisabled: boolean;
-    /** A description for the component. */
-    description: string;
-    /**
-     * When `true`, the component is draggable.
-     *
-     * @default false
-     */
-    dragEnabled: boolean;
-    /**
-     * When `true`, disables the default close on escape behavior.
-     *
-     * By default, an open dialog can be dismissed by pressing the Esc key.
-     *
-     * @see [Dialog Accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#accessibility).
-     * @default false
-     */
-    escapeDisabled: boolean;
-    /**
-     * Specifies custom focus trap configuration on the component, where
-     *
-     * `"allowOutsideClick`" allows outside clicks,
-     * `"initialFocus"` enables initial focus,
-     * `"returnFocusOnDeactivate"` returns focus when not active, and
-     * `"extraContainers"` specifies additional focusable elements external to the trap (e.g., 3rd-party components appending elements to the document body).
-     * `"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).
-     */
-    focusTrapOptions: Partial<FocusTrapOptions>;
-    /** The component header text. */
-    heading: string;
-    /** Specifies the heading level of the component's `heading` for proper document structure, without affecting visual styling. */
-    headingLevel: HeadingLevel;
-    /** Specifies the kind of the component, which will style the top border. */
-    kind: Extract<"brand" | "danger" | "info" | "success" | "warning", Kind>;
-    /** Specifies an icon to display. */
-    icon: IconName;
-    /**
-     * When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`).
-     *
-     * @default false
-     */
-    iconFlipRtl: boolean;
-    /**
-     * When `true`, a busy indicator is displayed.
-     *
-     * @default false
-     */
-    loading: boolean;
-    /**
-     * When `true`, the action menu items in the `header-menu-actions` slot are open.
-     *
-     * @default false
-     */
-    menuOpen: boolean;
-    /** Use this property to override individual strings used by the component. */
-    messageOverrides?: typeof this.messages._overrides;
-    /**
-     * When `true`, displays a scrim blocking interaction underneath the component.
-     *
-     * @default false
-     */
-    modal: boolean;
-    /**
-     * When `true` and `modal` is `false`, prevents focus trapping.
-     *
-     * @default false
-     */
-    focusTrapDisabled: boolean;
-    /**
-     * When `true`, displays and positions the component.
-     *
-     * @default false
-     */
-    get open(): boolean;
-    set open(value: boolean);
-    /**
-     * When `true`, disables the closing of the component when clicked outside.
-     *
-     * @default false
-     */
-    outsideCloseDisabled: boolean;
-    /**
-     * Determines the type of positioning to use for the overlaid content.
-     *
-     * Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
-     *
-     * `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.
-     *
-     * @default "absolute"
-     */
-    overlayPositioning: OverlayPositioning;
-    /**
-     * Specifies the placement of the dialog.
-     *
-     * @default "center"
-     */
-    placement: DialogPlacement;
-    /**
-     * When `true`, the component is resizable.
-     *
-     * @default false
-     */
-    resizable: boolean;
-    /**
-     * Specifies the size of the component.
-     *
-     * @default "m"
-     */
-    scale: Scale;
-    /**
-     * Specifies the width of the component.
-     *
-     * @deprecated in v3.0.0, removal target v6.0.0 - Use the `width` property instead.
-     * @default "m"
-     */
-    widthScale: Scale;
-    /** Specifies the width of the component. */
-    width: Extract<Width, Scale>;
-    /**
-     * Scrolls the component's content to a specified set of coordinates.
-     *
-     * @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).
-     * });
-     * @param options - allows specific coordinates to be defined.
-     * @returns - promise that resolves once the content is scrolled to.
-     */
-    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.
-     * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options)
-     * @returns - A promise that is resolved when the operation has completed.
-     */
-    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>;
-    /** Fires when the component is requested to be closed and before the closing transition begins. */
-    readonly calciteDialogBeforeClose: TargetedEvent<this, void>;
-    /** Fires when the component is added to the DOM but not rendered, and before the opening transition begins. */
-    readonly calciteDialogBeforeOpen: TargetedEvent<this, void>;
-    /** Fires when the component is closed and animation is complete. */
-    readonly calciteDialogClose: TargetedEvent<this, void>;
-    /** Fires when the component is open and animation is complete. */
-    readonly calciteDialogOpen: TargetedEvent<this, void>;
-    /** Fires when the content is scrolled. */
-    readonly calciteDialogScroll: TargetedEvent<this, void>;
-    private messages: Partial<{
-        close: string;
-        resizeEnabled: string;
-        dragEnabled: string;
-    }> & import('@arcgis/lumina/controllers').T9nMeta<{
-        close: string;
-        resizeEnabled: string;
-        dragEnabled: string;
-    }>;
-}
+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"];
+  };
+}