@esri/calcite-components/dist/types/utils/dom.d.ts

Web Components for Esri's Calcite Design System.

/**
 * The default `focus-trap/tabbable` options.
 *
 * See https://github.com/focus-trap/tabbable#tabbable
 */
export declare const tabbableOptions: {
  getShadowRoot: boolean;
};
/**
 * This helper will guarantee an ID on the provided element.
 *
 * If it already has an ID, it will be preserved, otherwise a unique one will be generated and assigned.
 *
 * @param {Element} el An element.
 * @returns {string} The element's ID.
 */
export declare function ensureId(el: Element): string;
/**
 * This helper returns an array from a NodeList.
 *
 * @param {NodeList} nodeList A NodeList.
 * @returns {Element[]} An array of elements.
 */
export declare function nodeListToArray<T extends Element>(nodeList: HTMLCollectionOf<T> | NodeListOf<T> | T[]): T[];
export type Direction = "ltr" | "rtl";
/**
 * This helper returns the Calcite "mode" of an element.
 *
 * @param {HTMLElement} el An element.
 * @returns {"light"|"dark"} The Calcite mode.
 */
export declare function getModeName(el: HTMLElement): "light" | "dark";
/**
 * This helper returns the direction of a HTML element.
 *
 * @param {HTMLElement} el An element.
 * @returns {Direction} The direction.
 */
export declare function getElementDir(el: HTMLElement): Direction;
/**
 * This helper returns the value of an attribute on an element.
 *
 * @param {HTMLElement} el An element.
 * @param {string} attribute An attribute name.
 * @param {any} fallbackValue A fallback value.
 * @returns {any} The value.
 * @deprecated
 */
export declare function getElementProp(el: Element, attribute: string, fallbackValue: any): any;
/**
 * This helper returns the rootNode of an element.
 *
 * @param {Element} el An element.
 * @returns {Document|ShadowRoot} The element's root node.
 */
export declare function getRootNode(el: Element): Document | ShadowRoot;
/**
 * This helper returns the node's shadowRoot root node if it exists.
 *
 * @param {Element} el The element.
 * @returns {ShadowRoot|null} The element's root node ShadowRoot.
 */
export declare function getShadowRootNode(el: Element): ShadowRoot | null;
/**
 * This helper returns the host of a ShadowRoot.
 *
 * @param {Document | ShadowRoot} root A root element.
 * @returns {Element | null} The host element.
 */
export declare function getHost(root: Document | ShadowRoot): Element | null;
/**
 * This helper queries an element's rootNode and any ancestor rootNodes.
 *
 * If both an 'id' and 'selector' are supplied, 'id' will take precedence over 'selector'.
 *
 * @param {Element} element An element.
 * @param root0
 * @param root0.selector
 * @param root0.id
 * @returns {Element} An element.
 */
export declare function queryElementRoots<T extends Element = Element>(element: Element, { selector, id }: {
  selector?: string;
  id?: string;
}): T | null;
/**
 * This helper returns the closest element matching the selector by crossing he shadow boundary if necessary.
 *
 * @param {Element} element The starting element.
 * @param {string} selector The selector.
 * @returns {Element} The targeted element.
 */
export declare function closestElementCrossShadowBoundary<T extends Element = Element>(element: Element, selector: string): T | null;
/**
 * This utility helps invoke a callback as it traverses a node and its ancestors until reaching the root document.
 *
 * Returning early or undefined in `onVisit` will continue traversing up the DOM tree. Otherwise, traversal will halt with the returned value as the result of the function
 *
 * @param {Element} element An element.
 * @param {(node: Node) => Element} onVisit The callback.
 * @returns {Element} The result.
 */
export declare function walkUpAncestry<T = any>(element: Element, onVisit: (node: Node) => T): T;
/**
 * This helper returns true when an element has the descendant in question.
 *
 * @param {Element} element The starting element.
 * @param {Element} maybeDescendant The descendant.
 * @returns {boolean} The result.
 */
export declare function containsCrossShadowBoundary(element: Element, maybeDescendant: Element): boolean;
/**
 * An element which may contain a `setFocus` method.
 */
export interface FocusableElement extends HTMLElement {
  setFocus?: () => Promise<void>;
}
/**
 * This helper returns true when an element has a setFocus method.
 *
 * @param {Element} el An element.
 * @returns {boolean} The result.
 */
export declare function isCalciteFocusable(el: FocusableElement): boolean;
/**
 * This helper focuses an element using the `setFocus` method if available and falls back to using the `focus` method if not available.
 *
 * @param {Element} el An element.
 */
export declare function focusElement(el: FocusableElement): Promise<void>;
/**
 * Helper to focus the first tabbable element.
 *
 * @param {HTMLElement} element The html element containing tabbable elements.
 */
export declare function focusFirstTabbable(element: HTMLElement): void;
interface GetSlottedOptions {
  all?: boolean;
  direct?: boolean;
  matches?: string;
  selector?: string;
}
/**
 * Gets slotted elements for a named slot.
 *
 * @param {Element} element An element.
 * @param {string} slotName The slot name.
 * @param {GetSlottedOptions & { all: true }} options The options.
 * @returns {Element | Element[] | null} returns element(s) or null.
 * @deprecated Use `onSlotchange` event instead.
 *
 * ```
 * <slot onSlotchange={(event) => this.myElements = slotChangeGetAssignedElements(event)} />}
 * ```
 */
export declare function getSlotted<T extends Element = Element>(element: Element, slotName: string | string[] | (GetSlottedOptions & {
  all: true;
}), options: GetSlottedOptions & {
  all: true;
}): T[];
export declare function getSlotted<T extends Element = Element>(element: Element, slotName?: string | string[] | GetSlottedOptions, options?: GetSlottedOptions): T | null;
/**
 * Filters direct children.
 *
 * @param {Element} el An element.
 * @param {string} selector The selector.
 * @returns {Element[]} An array of elements.
 */
export declare function filterDirectChildren<T extends Element>(el: Element, selector: string): T[];
/**
 * Set a default icon from a defined set or allow an override with an icon name string
 *
 * @param {Record<string, string>} iconObject The icon object.
 * @param {string | boolean} iconValue The icon value.
 * @param {string} matchedValue The matched value.
 * @returns {string|undefined} The resulting icon value.
 */
export declare function setRequestedIcon(iconObject: Record<string, string>, iconValue: string | boolean, matchedValue: string): string | undefined;
/**
 * This helper returns true when two rectangles intersect.
 *
 * @param {DOMRect} rect1 The first rectangle.
 * @param {DOMRect} rect2 The second rectangle.
 * @returns {boolean} The result.
 */
export declare function intersects(rect1: DOMRect, rect2: DOMRect): boolean;
/**
 * This helper makes sure that boolean aria attributes are properly converted to a string.
 *
 * It should only be used for aria attributes that require a string value of "true" or "false".
 *
 * @param {boolean} value The value.
 * @returns {string} The string conversion of a boolean value ("true" | "false").
 */
export declare function toAriaBoolean(value: boolean): string;
/**
 * This helper returns `true` if the target `slot` element from the `onSlotchange` event has an assigned element.
 *
 * ```
 * <slot onSlotchange={(event) => this.mySlotHasElement = slotChangeHasAssignedElement(event)} />}
 * ```
 *
 * @param {Event} event The event.
 * @returns {boolean} Whether the slot has any assigned elements.
 */
export declare function slotChangeHasAssignedElement(event: Event): boolean;
/**
 * This helper returns the assigned elements on a `slot` element from the `onSlotchange` event.
 *
 * ```
 * <slot onSlotchange={(event) => this.mySlotElements = slotChangeGetAssignedElements(event)} />}
 * ```
 *
 * @param {Event} event The event.
 * @returns {boolean} Whether the slot has any assigned elements.
 */
export declare function slotChangeGetAssignedElements(event: Event): Element[];
/**
 * This helper returns true if the pointer event fired from the primary button of the device.
 *
 * See https://www.w3.org/TR/pointerevents/#the-button-property.
 *
 * @param {PointerEvent} event The pointer event.
 * @returns {boolean} The value.
 */
export declare function isPrimaryPointerButton(event: PointerEvent): boolean;
export type FocusElementInGroupDestination = "first" | "last" | "next" | "previous";
/**
 * This helper sets focus on and returns a destination element from within a group of provided elements.
 *
 * @param {Element[]} elements An array of elements.
 * @param {Element} currentElement The current element.
 * @param {FocusElementInGroupDestination} destination The target destination element to focus.
 * @param {boolean} cycle Should navigation cycle through elements or stop at extent - defaults to true.
 * @returns {Element} The focused element
 */
export declare const focusElementInGroup: (elements: Element[], currentElement: Element, destination: FocusElementInGroupDestination, cycle?: boolean) => Element;
export {};