@arcgis/components-utils 4.33.0-next.16 → 4.33.0-next.161

package/dist/array-utils.d.cts

@@ -0,0 +1,5 @@
+import { Nil } from './types';
+/**
+ * Find a value in an array, and return it's mapped variant.
+ */
+export declare const mappedFind: <Item, ReturnType>(array: readonly Item[], callback: (item: Item, index: number) => Nil | ReturnType) => ReturnType | undefined;

package/dist/array-utils.d.ts

@@ -0,0 +1,5 @@
+import { Nil } from './types';
+/**
+ * Find a value in an array, and return it's mapped variant.
+ */
+export declare const mappedFind: <Item, ReturnType>(array: readonly Item[], callback: (item: Item, index: number) => Nil | ReturnType) => ReturnType | undefined;

package/dist/css-utils.d.cts

@@ -0,0 +1,15 @@
+import { Nil } from './types';
+/**
+ * This code contains imperative syntax (like for loops and mutation) as it is
+ * in the hot path - performance optimizations are critical here.
+ * See https://devtopia.esri.com/WebGIS/arcgis-js-api/commit/2565cedd87b
+ *
+ * Stencil has native support for passing-in class prop as an object or string,
+ * but it does not support arrays or booleans, thus this utility is used
+ * instead.
+ *
+ * @remarks
+ * This function is not necessary in a Lit package as Lit's `classMap` directive
+ * accepts an object
+ */
+export declare const classes: (...classes: (Nil | Record<string, boolean> | string[] | string | false)[]) => string;

package/dist/css-utils.d.ts

@@ -0,0 +1,15 @@
+import { Nil } from './types';
+/**
+ * This code contains imperative syntax (like for loops and mutation) as it is
+ * in the hot path - performance optimizations are critical here.
+ * See https://devtopia.esri.com/WebGIS/arcgis-js-api/commit/2565cedd87b
+ *
+ * Stencil has native support for passing-in class prop as an object or string,
+ * but it does not support arrays or booleans, thus this utility is used
+ * instead.
+ *
+ * @remarks
+ * This function is not necessary in a Lit package as Lit's `classMap` directive
+ * accepts an object
+ */
+export declare const classes: (...classes: (Nil | Record<string, boolean> | string[] | string | false)[]) => string;

package/dist/deferred.d.cts

@@ -0,0 +1,35 @@
+/**
+ * A deferred promise.
+ * Useful for when you want to return a promise but don't have the value yet.
+ * Example:
+ * ```
+ * const deferred = new Deferred<string>();
+ * setTimeout(() => deferred.resolve("Hello World"), 1000);
+ * return deferred.promise;
+ * ```
+ * @template T The type of the promise.
+ */
+export declare class Deferred<T> {
+    /**
+     * The promise that can be awaited.
+     */
+    promise: Promise<T>;
+    /**
+     * Creates a new deferred promise.
+     */
+    constructor();
+}
+export interface Deferred<T> {
+    /**
+     * Resolves the promise.
+     * @param value The value to resolve the promise with.
+     *
+     * @privateRemarks
+     * Defined as a method to disable covariance checks. Overridden in constructor.
+     */
+    resolve(_value: PromiseLike<T> | T): void;
+    /**
+     * Rejects the promise.
+     */
+    reject(_error: unknown): void;
+}

package/dist/deferred.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A deferred promise.
+ * Useful for when you want to return a promise but don't have the value yet.
+ * Example:
+ * ```
+ * const deferred = new Deferred<string>();
+ * setTimeout(() => deferred.resolve("Hello World"), 1000);
+ * return deferred.promise;
+ * ```
+ * @template T The type of the promise.
+ */
+export declare class Deferred<T> {
+    /**
+     * The promise that can be awaited.
+     */
+    promise: Promise<T>;
+    /**
+     * Creates a new deferred promise.
+     */
+    constructor();
+}
+export interface Deferred<T> {
+    /**
+     * Resolves the promise.
+     * @param value The value to resolve the promise with.
+     *
+     * @privateRemarks
+     * Defined as a method to disable covariance checks. Overridden in constructor.
+     */
+    resolve(_value: PromiseLike<T> | T): void;
+    /**
+     * Rejects the promise.
+     */
+    reject(_error: unknown): void;
+}

package/dist/dom.d.cts

@@ -0,0 +1,65 @@
+/**
+ * Observe the element and its ancestors for attribute mutations.
+ * If the attributes have been changed in the ancestor tree then the callback will be invoked.
+ * Example: `observeAncestorsMutation(element, ["dir", "lang"], () => console.log("dir or lang changed"));`
+ * @param element The element on which to observe the attribute mutations.
+ * @param attributeFilter The list of attributes to observe.
+ * @param callback The callback to invoke when the attributes have been changed.
+ * @returns The mutation observer
+ */
+export declare const observeAncestorsMutation: (element: Node, attributeFilter: string[], callback: () => void) => (() => void);
+/**
+ * Find the closest element that matches the selector.
+ * It will traverse the element's ancestors to find the target element.
+ * Shadow DOM boundaries are also taken into account.
+ * @param base The element to start the search from.
+ * @param selector The selector to match.
+ * @returns The closest element that matches the selector or null if not found.
+ */
+export declare const closestElement: (base: Element, selector: string) => Element | null;
+/**
+ * Use the Calcite mode to determine the theme of the element.
+ * It will traverse the element's ancestors to find the theme.
+ * Shadow DOM boundaries are also taken into account.
+ * @param base The element to start the search from.
+ * @returns The theme of the element, either "light" or "dark", "light" is the default.
+ */
+export declare const getElementTheme: (base: Element) => "dark" | "light";
+/**
+ * Get direction property of closest element.
+ * @param el The element to start the search from.
+ * @returns The direction of the element, either "ltr" | "rtl", "ltr" is the default.
+ */
+export declare const getElementDir: (el: HTMLElement) => "ltr" | "rtl";
+/**
+ * Get the attribute value from the element.
+ * It will traverse the element's ancestors to find the attribute.
+ * Shadow DOM boundaries are also taken into account.
+ * If the attribute is not found then the fallback value is returned.
+ * Example: `getElementAttribute(element, "dir", "ltr");`
+ * @param base The element to start the search from.
+ * @param prop The attribute name.
+ * @param fallbackValue The fallback value if the attribute is not found.
+ * @returns The attribute value or the fallback value if the attribute is not found.
+ */
+export declare const getElementAttribute: (el: Element, prop: string, fallbackValue: string) => string;
+export interface FocusableElement extends HTMLElement {
+    setFocus?: () => Promise<void>;
+}
+export declare const focusElement: (el: FocusableElement | undefined) => Promise<void>;
+/**
+ * Set the focus on the element that matches the selector.
+ * It will traverse the element's ancestors to find the target element.
+ * Shadow DOM boundaries are also taken into account.
+ * If the element is not found then the focus is not set.
+ * Example: `setFocusOnElement(element, "[role='menuitem']");`
+ * @param ref The element to start the search from.
+ * @param selector The selector to match.
+ * @returns Returns true if the focus is set on the element.
+ *
+ * REFACTOR: this is doing too much. break it into separate find element and focus
+ * element utilities
+ */
+export declare const setFocusOnElement: (ref: (Element & {
+    componentOnReady?: () => Promise<void>;
+}) | null | undefined, selector: string) => void;

package/dist/dom.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Observe the element and its ancestors for attribute mutations.
+ * If the attributes have been changed in the ancestor tree then the callback will be invoked.
+ * Example: `observeAncestorsMutation(element, ["dir", "lang"], () => console.log("dir or lang changed"));`
+ * @param element The element on which to observe the attribute mutations.
+ * @param attributeFilter The list of attributes to observe.
+ * @param callback The callback to invoke when the attributes have been changed.
+ * @returns The mutation observer
+ */
+export declare const observeAncestorsMutation: (element: Node, attributeFilter: string[], callback: () => void) => (() => void);
+/**
+ * Find the closest element that matches the selector.
+ * It will traverse the element's ancestors to find the target element.
+ * Shadow DOM boundaries are also taken into account.
+ * @param base The element to start the search from.
+ * @param selector The selector to match.
+ * @returns The closest element that matches the selector or null if not found.
+ */
+export declare const closestElement: (base: Element, selector: string) => Element | null;
+/**
+ * Use the Calcite mode to determine the theme of the element.
+ * It will traverse the element's ancestors to find the theme.
+ * Shadow DOM boundaries are also taken into account.
+ * @param base The element to start the search from.
+ * @returns The theme of the element, either "light" or "dark", "light" is the default.
+ */
+export declare const getElementTheme: (base: Element) => "dark" | "light";
+/**
+ * Get direction property of closest element.
+ * @param el The element to start the search from.
+ * @returns The direction of the element, either "ltr" | "rtl", "ltr" is the default.
+ */
+export declare const getElementDir: (el: HTMLElement) => "ltr" | "rtl";
+/**
+ * Get the attribute value from the element.
+ * It will traverse the element's ancestors to find the attribute.
+ * Shadow DOM boundaries are also taken into account.
+ * If the attribute is not found then the fallback value is returned.
+ * Example: `getElementAttribute(element, "dir", "ltr");`
+ * @param base The element to start the search from.
+ * @param prop The attribute name.
+ * @param fallbackValue The fallback value if the attribute is not found.
+ * @returns The attribute value or the fallback value if the attribute is not found.
+ */
+export declare const getElementAttribute: (el: Element, prop: string, fallbackValue: string) => string;
+export interface FocusableElement extends HTMLElement {
+    setFocus?: () => Promise<void>;
+}
+export declare const focusElement: (el: FocusableElement | undefined) => Promise<void>;
+/**
+ * Set the focus on the element that matches the selector.
+ * It will traverse the element's ancestors to find the target element.
+ * Shadow DOM boundaries are also taken into account.
+ * If the element is not found then the focus is not set.
+ * Example: `setFocusOnElement(element, "[role='menuitem']");`
+ * @param ref The element to start the search from.
+ * @param selector The selector to match.
+ * @returns Returns true if the focus is set on the element.
+ *
+ * REFACTOR: this is doing too much. break it into separate find element and focus
+ * element utilities
+ */
+export declare const setFocusOnElement: (ref: (Element & {
+    componentOnReady?: () => Promise<void>;
+}) | null | undefined, selector: string) => void;

package/dist/errors.d.cts

@@ -0,0 +1,30 @@
+/**
+ * Check whether the code is executing in an Esri internal environment (for
+ * example, Lumina dev server). When true, your code can enable extra validation
+ * to detect incorrect usages or do runtime bug detection.
+ *
+ * The call to isEsriInternalEnv() MUST always appear behind one of the
+ * following guards to ensure it is correctly eliminated in production bundles:
+ *
+ * - `process.env.NODE_ENV !== "production"`
+ * - `process.env.NODE_ENV === "development"`
+ * - `process.env.NODE_ENV === "test"`
+ *
+ * @remarks
+ * This function is primary for usage in support packages. In Lumina component
+ * packages, simpler alternatives are provided:
+ * https://qawebgis.esri.com/components/lumina/publishing#bundling-code-conditionally
+ */
+export declare const isEsriInternalEnv: () => boolean;
+/**
+ * Calls a sync method and catch any errors. Returns undefined if error occurred.
+ *
+ * Can also provide a thisContext and rest arguments
+ */
+export declare const safeCall: <Callback extends (...args: never[]) => unknown>(callback?: Callback, thisContext?: ThisParameterType<Callback>, ...rest: Parameters<Callback>) => ReturnType<Callback> | void;
+/**
+ * Calls an async method and catch any errors. Returns undefined if error occurred.
+ *
+ * Can also provide a thisContext and rest arguments
+ */
+export declare const safeAsyncCall: <Callback extends (...args: never[]) => unknown>(callback?: Callback, thisContext?: ThisParameterType<Callback>, ...rest: Parameters<Callback>) => Promise<Awaited<ReturnType<Callback>> | void>;

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Check whether the code is executing in an Esri internal environment (for
+ * example, Lumina dev server). When true, your code can enable extra validation
+ * to detect incorrect usages or do runtime bug detection.
+ *
+ * The call to isEsriInternalEnv() MUST always appear behind one of the
+ * following guards to ensure it is correctly eliminated in production bundles:
+ *
+ * - `process.env.NODE_ENV !== "production"`
+ * - `process.env.NODE_ENV === "development"`
+ * - `process.env.NODE_ENV === "test"`
+ *
+ * @remarks
+ * This function is primary for usage in support packages. In Lumina component
+ * packages, simpler alternatives are provided:
+ * https://qawebgis.esri.com/components/lumina/publishing#bundling-code-conditionally
+ */
+export declare const isEsriInternalEnv: () => boolean;
+/**
+ * Calls a sync method and catch any errors. Returns undefined if error occurred.
+ *
+ * Can also provide a thisContext and rest arguments
+ */
+export declare const safeCall: <Callback extends (...args: never[]) => unknown>(callback?: Callback, thisContext?: ThisParameterType<Callback>, ...rest: Parameters<Callback>) => ReturnType<Callback> | void;
+/**
+ * Calls an async method and catch any errors. Returns undefined if error occurred.
+ *
+ * Can also provide a thisContext and rest arguments
+ */
+export declare const safeAsyncCall: <Callback extends (...args: never[]) => unknown>(callback?: Callback, thisContext?: ThisParameterType<Callback>, ...rest: Parameters<Callback>) => Promise<Awaited<ReturnType<Callback>> | void>;

package/dist/guid.d.cts

@@ -0,0 +1,5 @@
+/**
+ * Generates a GUID string.
+ * @returns A GUID string with the pattern 00000000-0000-0000-0000-000000000000.
+ */
+export declare const generateGuid: () => string;

package/dist/guid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a GUID string.
+ * @returns A GUID string with the pattern 00000000-0000-0000-0000-000000000000.
+ */
+export declare const generateGuid: () => string;