@esri/calcite-components
Version:
Web Components for Esri's Calcite Design System.
364 lines (363 loc) • 15.3 kB
TypeScript
import { IconNameOrString } from '../components/calcite-icon/interfaces';
/**
* 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 computed width in pixels of a rendered HTMLElement.
*
* @param {HTMLElement} el An element.
* @returns {number} The element's width.
*/
export declare function getElementWidth(el: HTMLElement): number;
/**
* 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 computed width in pixels a given text string takes up on screen.
*
* See https://stackoverflow.com/questions/118241/calculate-text-width-with-javascript
*
* @param {string} text The string of text to measure.
* @param {string} font The CSS font attribute's value, which should include size and face, e.g. "12px Arial".
*/
export declare function getTextWidth(text: string, font: string): number;
/**
* 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} el An element.
* @param root0
* @param root0.selector
* @param root0.id
* @returns {Element} An element.
*/
export declare function queryElementRoots<T extends Element = Element>(el: 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.
*
* Based on https://stackoverflow.com/q/54520554/194216
*
* @param {Element} element The starting element.
* @param {string} selector The selector.
* @returns {Element} The targeted element.
*/
export declare function closestElementCrossShadowBoundary<TagName extends keyof HTMLElementTagNameMap>(element: Element, selector: TagName): HTMLElementTagNameMap[TagName] | null;
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 get the first tabbable element.
*
* @param {HTMLElement} element The html element containing tabbable elements.
* @returns the first tabbable element.
*/
export declare function getFirstTabbable(element: HTMLElement): HTMLElement;
/**
* Helper to focus the first tabbable element.
*
* @param {HTMLElement} element The html element containing tabbable elements.
*/
export declare function focusFirstTabbable(element: HTMLElement): void;
/**
* 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[];
/**
* Filters an array of HTML elements by the provided css selector string.
*
* @param {Element[]} elements An array of elements, such as one returned by HTMLSlotElement.assignedElements().
* @param {string} selector The CSS selector string to filter the returned elements by.
* @returns {Element[]} A filtered array of elements.
*/
export declare function filterElementsBySelector<T extends Element>(elements: 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, IconNameOrString>, iconValue: IconNameOrString | boolean | "", matchedValue: string): IconNameOrString | 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 any content (text or elements).
*
* ```
* <slot onSlotchange={(event) => this.mySlotHasContent = slotChangeHasContent(event)} />}
* ```
*
* @param {Event} event The event.
* @returns {boolean} Whether the slot has any content.
*/
export declare function slotChangeHasContent(event: Event): boolean;
/**
* This helper returns a string of textContent if the target `slot` element from the `onSlotchange` event has any text content.
*
* ```
* <slot onSlotchange={(event) => this.mySlotText = slotChangeGetTextContent(event)} />}
* ```
*
* @param {Event} event The event.
* @returns {string} The slots text.
*/
export declare function slotChangeGetTextContent(event: Event): string;
/**
* This helper checks if an element has visible content.
*
* @param {HTMLElement} element The element to check.
* @returns {boolean} True if the element has visible content, otherwise false.
*/
export declare function hasVisibleContent(element: HTMLElement): boolean;
/**
* This helper returns `true` if the target `slot` element from the `onSlotchange` event has any text content.
*
* ```
* <slot onSlotchange={(event) => this.mySlotHasTextContent = slotChangeHasTextContent(event)} />}
* ```
*
* @param {Event} event The event.
* @returns {boolean} Whether the slot has any text content.
*/
export declare function slotChangeHasTextContent(event: Event): boolean;
/**
* This helper returns `true` if the target `slot` element from the `onSlotchange` event has an assigned node.
*
* ```
* <slot onSlotchange={(event) => this.mySlotHasNode = slotChangeHasAssignedNode(event)} />}
* ```
*
* @param {Event} event The event.
* @returns {boolean} Whether the slot has any assigned nodes.
*/
export declare function slotChangeHasAssignedNode(event: Event): boolean;
/**
* This helper returns the assigned nodes on a `slot` element from the `onSlotchange` event.
*
* ```
* <slot onSlotchange={(event) => this.mySlotNodes = slotChangeGetAssignedNodes(event)} />}
* ```
*
* @param {Event} event The event.
* @returns {boolean} Whether the slot has any assigned nodes.
*/
export declare function slotChangeGetAssignedNodes(event: Event): Node[];
/**
* 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.
* @param {string} selector The CSS selector string to filter the returned elements by.
* @returns {Element[]} An array of elements.
*/
export declare function slotChangeGetAssignedElements<T extends Element>(event: Event, selector?: string): T[] | null;
/**
* This helper returns the assigned elements on a `slot` element, filtered by an optional css selector.
*
* @param {HTMLSlotElement} slot The slot element.
* @param {string} selector CSS selector string to filter the returned elements by.
* @returns {Element[]} An array of elements.
*/
export declare function getSlotAssignedElements<T extends Element>(slot: HTMLSlotElement, selector?: string): T[] | null;
/**
* 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;
/**
* This helper returns true if the mouse event was triggered by a keyboard click.
*
* @param {MouseEvent} event The mouse event.
* @returns {boolean} The value.
*/
export declare function isKeyboardTriggeredClick(event: MouseEvent): 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: <T extends Element = Element>(elements: Element[], currentElement: Element, destination: FocusElementInGroupDestination, cycle?: boolean) => T;
/**
* This helper determines if an element is before another element in the DOM.
*
* @param a the reference element to compare
* @param b the element to compare against
* @returns true when a is before b in the DOM
*/
export declare function isBefore(a: HTMLElement, b: HTMLElement): boolean;
/**
* This util helps determine when an animation has completed.
*
* @param targetEl The element to watch for the animation to complete.
* @param animationName The name of the animation to watch for completion.
* @param onStart A callback to run when the animation starts.
* @param onEnd A callback to run when the animation ends or is canceled.
*/
export declare function whenAnimationDone(targetEl: HTMLElement, animationName: string, onStart?: () => void, onEnd?: () => void): Promise<void>;
/**
* This util helps determine when a transition has completed.
*
* @param targetEl The element to watch for the transition to complete.
* @param transitionProp The name of the transition to watch for completion.
* @param onStart A callback to run when the transition starts.
* @param onEnd A callback to run when the transition ends or is canceled.
*/
export declare function whenTransitionDone(targetEl: HTMLElement, transitionProp: string, onStart?: () => void, onEnd?: () => void): Promise<void>;
type TransitionOrAnimation = "transition" | "animation";
/**
* This util helps determine when a transition has completed.
*
* @param targetEl The element to watch for the transition or animation to complete.
* @param transitionPropOrAnimationName The transition or animation property to watch for completion.
* @param type The type of property to watch for completion. Defaults to "transition".
* @param onStart A callback to run when the transition or animation starts.
* @param onEnd A callback to run when the transition or animation ends or is canceled.
*/
export declare function whenTransitionOrAnimationDone(targetEl: HTMLElement, transitionPropOrAnimationName: string, type: TransitionOrAnimation, onStart?: () => void, onEnd?: () => void): Promise<void>;
/**
* This helper converts a CSS style value (e.g., "px", "vw", "vh") into its pixel equivalent.
*
* - If the value ends with "px", it parses and returns the numeric value.
* - If the value ends with "vw", it calculates the pixel value based on the viewport width.
* - If the value ends with "vh", it calculates the pixel value based on the viewport height.
* - For unsupported units or invalid values, it returns 0.
*
* @param {string} value - The CSS style value to convert (e.g., "10px", "50vw", "30vh").
* @returns {number} The pixel equivalent of the provided value.
*/
export declare function getStylePixelValue(value: string): number;
export {};