@arcgis/toolkit 5.2.0-next.14 → 5.2.0-next.141

package/dist/{string/index.d.ts → string.d.ts}

@@ -1,6 +1,8 @@
 /**
  * Convert kebab-case string to PascalCase
  *
+ * @public
+ * @param string
  * @example
  * ```ts
  * const pascal = kebabToPascal("my-component-name");
@@ -10,6 +12,8 @@ export declare const kebabToPascal: (string: string) => string;
 /**
  * Convert camelCase string to kebab-case
  *
+ * @public
+ * @param string
  * @example
  * ```ts
  * const kebab = camelToKebab("myComponentName");
@@ -20,6 +24,8 @@ export declare const camelToKebab: (string: string) => string;
 /**
  * Convert camelCase string to Sentence case.
  *
+ * @public
+ * @param string
  * @example
  * ```ts
  * const human = camelToHuman("myComponentName");
@@ -27,26 +33,44 @@ export declare const camelToKebab: (string: string) => string;
  * ```
  */
 export declare const camelToHuman: (string: string) => string;
-/** Capitalize the first letter of a string. */
+/**
+ * Capitalize the first letter of a string.
+ *
+ * @public
+ * @param string
+ */
 export declare const capitalize: <T extends string>(string: T) => Capitalize<T>;
-/** Uncapitalize the first letter of a string. */
+/**
+ * Uncapitalize the first letter of a string.
+ *
+ * @public
+ * @param string
+ */
 export declare const uncapitalize: <T extends string>(string: T) => Uncapitalize<T>;
 /**
  * Add quotes to a string for display purposes.
  * If the string contains a double quote, then single quotes will be used.
  * If the string contains a single quote, then double quotes will be used.
  * If the string contains both, then double quotes will be used and the single quotes will be escaped.
+ *
+ * @public
+ * @param value
  */
 export declare const quoteString: (value: string) => string;
 /**
  * Create a filter expression from a filter word.
  *
- * @remarks Once browser support permits, use `RegExp.escape()` instead.
+ * > Once browser support permits, use `RegExp.escape()` instead.
+ *
+ * @public
+ * @param filterWord
  * @privateRemarks TODO: DEPRECATE
  */
 export declare const createFilterExpression: (filterWord: string) => RegExp;
 /**
  * Add LTR marks to a string to ensure it is displayed as LTR even in RTL contexts.
+ *
+ * @public
  * @param value The string to add LTR marks to.
  * @returns The string with LTR marks.
  *
@@ -58,6 +82,8 @@ export declare const createFilterExpression: (filterWord: string) => RegExp;
 export declare const addLtrMark: (value: string | undefined) => string;
 /**
  * A string containing a randomly generated, 36 character long v4 UUID.
+ *
+ * @public
  */
 export type UUID = ReturnType<typeof crypto.randomUUID>;
 /**
@@ -69,6 +95,7 @@ export type UUID = ReturnType<typeof crypto.randomUUID>;
  * Avoid using GUID and other non-deterministic output in render() as they
  * cause SSR hydration issues and snapshot test instability.
  *
+ * @public
  * @example
  * ```ts
  * const id = generateGuid();
@@ -79,6 +106,8 @@ export declare const generateGuid: () => UUID;
 /**
  * Extract the major and minor version from a full version string.
  *
+ * @public
+ * @param version
  * @example
  * ```ts
  * const minorVersion = getMinorVersion("4.34.0-next.123");
@@ -93,6 +122,8 @@ export declare const getMinorVersion: (version: string) => string;
  * The version number should normally come from package.json.
  *
  * @see https://webgis.esri.com/sdk/contributing/licensing
+ * @public
+ * @param version
  * @example
  * ```ts
  * const preamble = getPreamble("5.0.1-next.456");
@@ -104,6 +135,9 @@ export declare const getPreamble: (version: string) => string;
  * Replace values in a string using the format {valueName} with the value from the values object.
  * If the value is not found in the values object, then the value is not replaced.
  *
+ * @public
+ * @param message
+ * @param values
  * @deprecated Import from https://next.gha.afd.arcgis.com/javascript/latest/references/core/intl/#substitute instead
  */
 export declare const setValuesInString: (message: string | null | undefined, values?: Record<string, string>) => string;
@@ -113,6 +147,9 @@ export declare const setValuesInString: (message: string | null | undefined, val
  *
  * Throws when the named region cannot be found or is missing its closing marker.
  *
+ * @public
+ * @param source
+ * @param regionName
  * @example
  * ```ts
  * import code from "my-code-file.ts?raw";

package/dist/{type/index.d.ts → type.d.ts}

@@ -1,15 +1,24 @@
 /**
  * A convenient alias for `null | undefined`.
- * @remarks Named `nil` over `Nil` as per https://devtopia.esri.com/WebGIS/arcgis-js-api/pull/66920
+ *
+ * > Named `nil` over `Nil` as per https://devtopia.esri.com/WebGIS/arcgis-js-api/pull/66920
+ *
+ * @public
  */
 export type nil = null | undefined;
 /**
+ * @public
  * @deprecated import type { ResourceHandle } from "@arcgis/core/core/Handles.js";
  */
 export type IHandle = {
+    /**
+     * @public
+     * @deprecated import type { ResourceHandle } from "@arcgis/core/core/Handles.js";
+     */
     remove: () => void;
 };
 /**
+ * @public
  * @deprecated Import type { nil } from `@arcgis/toolkit/type` instead
  */
 export type Nil = nil;
@@ -23,6 +32,7 @@ export type Nil = nil;
  * During production end-application build, such type tests will be removed as
  * they have no runtime impact.
  *
+ * @public
  * @privateRemarks
  * Using `0` over `undefined` to take fewer bytes if minifier is disabled.
  */

package/dist/{url/index.d.ts → url.d.ts}

@@ -1,6 +1,7 @@
 /**
  * Compares two url strings for their origin and returns true if they have the same origin.
  *
+ * @public
  * @param url1 First url string
  * @param url2 Second url string
  * @param ignoreProtocol Indicates if protocol comparison should be ignored
@@ -9,10 +10,10 @@
 export declare const hasSameOrigin: (url1: string | null | undefined, url2: string | null | undefined, ignoreProtocol?: boolean) => boolean;
 /**
  * Tests if a url string is a URL or not.
+ *
+ * @public
+ * @deprecated Use https://developer.mozilla.org/docs/Web/API/URL/parse_static instead
  * @param url The url string to test
  * @returns True if the string is a URL.
- *
- * @remarks If browser support permits, use https://developer.mozilla.org/docs/Web/API/URL/parse_static instead
- * @privateRemarks TODO: DEPRECATE
  */
 export declare const isURL: (url: string) => boolean;

package/package.json

@@ -1,23 +1,27 @@
 {
   "name": "@arcgis/toolkit",
-  "version": "5.2.0-next.14",
+  "version": "5.2.0-next.141",
   "description": "Collection of common internal patterns and utilities for ArcGIS Maps SDK for JavaScript components.",
   "homepage": "https://developers.arcgis.com/javascript/latest/",
   "sideEffects": false,
   "type": "module",
   "exports": {
-    "./array": "./dist/array/index.js",
-    "./dom": "./dist/dom/index.js",
-    "./error": "./dist/error/index.js",
-    "./function": "./dist/function/index.js",
-    "./intl": "./dist/intl/index.js",
-    "./log": "./dist/log/index.js",
-    "./number": "./dist/number/index.js",
-    "./predicate": "./dist/predicate/index.js",
-    "./promise": "./dist/promise/index.js",
-    "./string": "./dist/string/index.js",
-    "./type": "./dist/type/index.js",
-    "./url": "./dist/url/index.js",
+    "./array": "./dist/array.js",
+    "./dom": "./dist/dom.js",
+    "./dom/color": "./dist/dom/color.js",
+    "./dom/slots": "./dist/dom/slots.js",
+    "./dom/referenceElement": "./dist/dom/referenceElement.js",
+    "./error": "./dist/error.js",
+    "./function": "./dist/function.js",
+    "./intl": "./dist/intl.js",
+    "./intl/dom": "./dist/intl/dom.js",
+    "./log": "./dist/log.js",
+    "./number": "./dist/number.js",
+    "./predicate": "./dist/predicate.js",
+    "./promise": "./dist/promise.js",
+    "./string": "./dist/string.js",
+    "./type": "./dist/type.js",
+    "./url": "./dist/url.js",
     "./package.json": "./package.json"
   },
   "files": [

package/dist/dom/index.d.ts

@@ -1,117 +0,0 @@
-import { nil } from '../type/index.ts';
-export * from './slots.ts';
-export * from './reference-element.ts';
-/**
- * Combine multiple class names into a single string.
- *
- * @remarks
- * This function is less necessary in Lumina packages as the `class` JSX prop
- * accepts `Record<string, boolean>` objects.
- */
-export declare const classes: (...classes: (nil | Record<string, boolean> | string[] | string | false)[]) => string;
-/**
- * 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.
- *
- * @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 A callback to unsubscribe from the observer.
- *
- * @example
- * ```ts
- * observeAncestorsMutation(
- *   element,
- *   ["dir", "lang"],
- *   () => console.log(getElementAttribute(element, "dir", "ltr"))
- * );
- * ```
- */
-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.
- *
- * @remarks
- * This is similar to [Element.closest()](https://developer.mozilla.org/docs/Web/API/Element/closest),
- * but the DOM's utility only looks up until the first shadow boundary.
- *
- * @example
- * ```ts
- * const hostElement = getClosestElement(element, "arcgis-map, arcgis-scene");
- * ```
- */
-export declare const getClosestElement: <T = Element>(base: Element, selector: string) => T | undefined;
-/**
- * Use the closest Calcite mode class name 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 ("light" or "dark"). "light" is the default.
- *
- * @remarks
- * It is advised to consider alternative solutions before using this utility:
- * - Calcite CSS variables. Benefits: makes styles more consistent,
- *   and variables are updated automatically to match dark/light theme.
- * - Detect dark mode using CSS selectors and apply styles in CSS.
- *   Benefit: styles update automatically when the theme changes.
- */
-export declare function unsafeGetCalciteModeName(el: HTMLElement): "dark" | "light";
-/**
- * Get direction property of the closest element.
- *
- * @param el The element to start the search from.
- * @returns The direction of the element ("ltr" | "rtl"). "ltr" is the default.
- *
- * @remarks
- * Do not set the `dir` property on the element itself. Do not set the `dir`
- * attribute on the components you are rendering. The `dir` attribute is only
- * meant to be set by the consumers of your component. Your component is
- * expected to respect what was set by the consumer.
- *
- * @remarks
- * Prefer [useDirection()](https://webgis.esri.com/references/lumina/controllers/useDirection)
- * to ensure your component is responsive to direction changes.
- */
-export declare const unsafeGetElementDirection: (el: HTMLElement) => "ltr" | "rtl";
-/**
- * Get the attribute value from the element or closest ancestor.
- * Shadow DOM boundaries are also taken into account.
- * If the attribute is not found then the fallback value is returned.
- *
- * @example
- * ```ts
- * const dir = getElementAttribute(element, "dir", "ltr");
- * ```
- */
-export declare const getElementAttribute: (el: Element, attributeName: string, fallbackValue: string) => string;
-/**
- * Focus the element if it is focusable.
- * @returns A promise that resolves once the focus is set.
- */
-export declare const focusElement: (el: FocusableElement | undefined) => Promise<void>;
-export interface FocusableElement extends HTMLElement {
-    setFocus?: () => 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.
- *
- * @deprecated This function is doing too much. Import from `focusElement(getClosestElement())` from `@arcgis/toolkit/dom` instead.
- */
-export declare const setFocusOnElement: (ref: (Element & {
-    componentOnReady?: () => Promise<void>;
-}) | null | undefined, selector: string) => void;

package/dist/dom/reference-element.d.ts

@@ -1,6 +0,0 @@
-type ArcgisComponentBase<T> = {
-    el: HTMLElement;
-    referenceElement?: T | string | null | undefined;
-};
-export declare function resolveReferenceElement<T extends Element>(component: ArcgisComponentBase<T>, referenceElementString?: ArcgisComponentBase<T>["referenceElement"] | string): T | undefined;
-export {};

package/dist/intl/index.d.ts

@@ -1,124 +0,0 @@
-declare const supportedLocalesArray: ["ar", "bg", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "fi", "fr", "he", "hr", "hu", "id", "it", "ja", "ko", "lt", "lv", "nl", "nb", "no", "pl", "pt-BR", "pt-PT", "ro", "ru", "sk", "sl", "sr", "sv", "th", "tr", "uk", "vi", "zh-CN", "zh-HK", "zh-TW"];
-/**
- * The list of supported locales for ArcGIS Maps SDK for JavaScript components.
- */
-export declare const supportedLocales: Set<"hr" | "th" | "tr" | "el" | "ar" | "bg" | "bs" | "ca" | "cs" | "da" | "de" | "en" | "es" | "et" | "fi" | "fr" | "he" | "hu" | "id" | "it" | "ja" | "ko" | "lt" | "lv" | "nl" | "nb" | "no" | "pl" | "pt-BR" | "pt-PT" | "ro" | "ru" | "sk" | "sl" | "sr" | "sv" | "uk" | "vi" | "zh-CN" | "zh-HK" | "zh-TW">;
-/**
- * TypeScript union type for each locale supported by WebGIS SDK
- */
-export type SupportedLocale = (typeof supportedLocalesArray)[number];
-/**
- * The default locale for WebGIS SDK.
- */
-export declare const defaultLocale = "en";
-/**
- * Fetch the T9N strings bundle for the given locale, assets path and prefix.
- * The locale must be one of the supported locales.
- * If the locale is not supported, it will default to 'en'.
- * If the T9N strings bundle cannot be found, it will default to 'en'.
- *
- * @param locale The locale for which to fetch the T9N strings
- * @param assetsPath The path to the assets folder where the T9N strings are located
- * @param prefix The prefix to use for the T9N strings file name.
- *
- * @remarks
- * Rather than using this function directly, prefer the
- * [useT9n()](https://webgis.esri.com/references/lumina/controllers/useT9n)
- * controller.
- *
- * @remarks
- * The function implements cache. Frequent calls are safe.
- *
- * @example
- * ```ts
- * // Will make a request for ./assets/coding-editor/t9n/messages.en.json
- * const t9nStrings = await fetchT9nStringsBundle(
- *   "en",
- *   getAssetPath("./assets/coding-editor/t9n"),
- *   "messages."
- * );
- * ```
- *
- * @see [Lumina asset handling](https://webgis.esri.com/references/lumina/assets)
- */
-export declare const fetchT9nStringsBundle: <Strings extends GenericT9nStrings>(locale: string, assetsPath: string, prefix?: string) => Promise<Strings>;
-/**
- * The interface for translated strings.
- */
-export interface GenericT9nStrings {
-    [key: string]: GenericT9nStrings | string;
-}
-/**
- * Get the locale of the given element.
- * It will look for the lang attribute on the element and its ancestors.
- * If not lang is found, it will default to 'en'.
- *
- * @returns an object with the `lang` and `t9nLocale` properties.
- *
- * @see [lang vs t9nLocale](https://webgis.esri.com/references/lumina/controllers/useT9n#difference-between-lang-and-t9nlocale).
- */
-export declare const getElementLocale: (element: HTMLElement) => {
-    readonly lang: string;
-    readonly t9nLocale: SupportedLocale;
-};
-/**
- * Try to parse any language string into one of the locales supported by WebGIS SDK.
- *
- * @remarks
- * Follows the ArcGIS Maps SDK for JavaScript locale support:
- * https://developers.arcgis.com/javascript/latest/localization/#locale-support
- *
- * If language includes a region code, but we don't have a bundle for it, the
- * language is normalized to the language code only.
- */
-export declare const normalizeLocale: (lang: string) => SupportedLocale;
-export interface LocaleObserverResult<Strings extends GenericT9nStrings = GenericT9nStrings> {
-    /** The T9N strings of the component */
-    t9nStrings: Strings;
-    /**
-     * The locale of the component set by the `lang` attribute on the component host element or one of its ancestors.
-     */
-    lang: string;
-    /**
-     * The locale used by the component to load the T9N strings.
-     * It may be different than the locale of the component host element that was set by the `lang` attribute.
-     */
-    t9nLocale: SupportedLocale;
-}
-/**
- * Start the locale observer for the given component.
- * The callback will be called when the locale changes for the component.
- * It will observe the lang attribute on the component and its ancestors.
- * The callback is called once at the beginning.
- *
- * @param element The HTML element that is doing the fetching
- *   This is used to determine the locale to fetch, observe the `lang` attribute
- *   changes, and is used as the default value for the `assetName` parameter.
- * @param getAssetsPath The callback to get path to the assets folder where the
- *   T9N strings are located.
- * @param onUpdated The callback to call when the locale changes.
- * @param assetName Optionally override the asset file name.
- *   Default file name is the element tag name without the part before the
- *   first dash (e.g. `arcgis-map` becomes `map`).
- *
- *   Set to null if the component has no localization strings, but you still
- *   wish to use `startLocaleObserver` to get the locale information.
- *
- * @remarks
- * Rather than using this function directly, prefer the
- * [useT9n()](https://webgis.esri.com/references/lumina/controllers/useT9n)
- * controller.
- *
- * @example
- * ```ts
- * const observer = startLocaleObserver(
- *   element,
- *   () => getAssetPath("./assets"),
- *   ({ strings, lang, t9nLocale }) => console.log({ strings, lang, t9nLocale }),
- * );
- * // Later: cleanup
- * observer();
- * ```
- */
-export declare const startLocaleObserver: <Strings extends GenericT9nStrings = GenericT9nStrings>(element: HTMLElement, getAssetsPath: () => string, onUpdated: (payload: LocaleObserverResult<Strings>) => void, assetName?: string | null) => (() => void);
-export {};

package/dist/predicate/index.d.ts

@@ -1,24 +0,0 @@
-import { nil } from '../type/index.ts';
-/**
- * Safeguard to ensure that an item is not undefined.
- * @param item The item to check.
- * @returns Returns true if the item is not undefined.
- * @example
- * ```ts
- * const arr = [1, undefined, 3];
- * const result = arr.filter(isNotUndefined);
- * ```
- */
-export declare const isNotUndefined: <T>(item: T | undefined) => item is T;
-/**
- * Safeguard to ensure that an item is not null.
- * @param item The item to check.
- * @returns Returns true if the item is not null.
- */
-export declare const isNotNull: <T>(item: T | null) => item is T;
-/**
- * Safeguard to ensure that an item is not null.
- * @param item The item to check.
- * @returns Returns true if the item is not and not undefined and not null.
- */
-export declare const isNotNil: <T>(x: nil | T) => x is T;

package/dist/predicate/index.js

@@ -1,8 +0,0 @@
-const isNotUndefined = (item) => item !== void 0;
-const isNotNull = (item) => item !== null;
-const isNotNil = (x) => x != null;
-export {
-  isNotNil,
-  isNotNull,
-  isNotUndefined
-};