@arcgis/components-utils 4.33.0-next.9 → 4.33.0-next.90

package/dist/intl.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The interface for translated strings.
+ */
+export interface GenericT9nStrings {
+    [key: string]: GenericT9nStrings | string;
+}
+declare const supportedLocalesArray: readonly ["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" | "ar" | "bg" | "bs" | "ca" | "cs" | "da" | "de" | "el" | "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">;
+export type SupportedLocale = (typeof supportedLocalesArray)[number];
+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'.
+ *
+ * @remarks
+ * Rather than using this function directly, prefer the `useT9n()` controller.
+ *
+ * @example
+ * ```ts
+ * const t9nStrings = await fetchT9nStringsBundle("en", getAssetPath("./assets/coding-editor/t9n"), "messages.");
+ * ```
+ */
+export declare function fetchT9nStringsBundle<Strings extends GenericT9nStrings>(
+/** The locale for which to fetch the T9N strings  */
+locale: string, 
+/** The path to the assets folder where the T9N strings are located */
+assetsPath: string, 
+/** The prefix to use for the T9N strings file name. */
+prefix?: string): Promise<Strings>;
+/**
+ * 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'.
+ */
+export declare function getElementLocales(element: HTMLElement): {
+    readonly lang: string;
+    readonly t9nLocale: SupportedLocale;
+};
+export declare function normalizeLocale(locale: string): SupportedLocale;
+export type LocaleObserver<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.
+ *
+ * @remarks
+ * Rather than using this function directly, prefer the `useT9n()` controller.
+ */
+export declare function startLocaleObserver<Strings extends GenericT9nStrings = GenericT9nStrings>(
+/** The Web component HTML element that is doing the fetching */
+element: HTMLElement, 
+/**
+ * The callback to get path to the assets folder where the T9N strings are
+ * located.
+ *
+ * @example
+ * ```ts
+ * () => getAssetPath("./assets")
+ * ```
+ */
+getAssetsPath: () => string, 
+/** The callback to call when the locale changes  */
+onUpdated: (payload: LocaleObserver<Strings>) => void, 
+/**
+ * Optionally override the asset file name.
+ * Default file name is the component 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.
+ */
+assetName?: string | null): () => void;
+export {};

package/dist/preamble.d.cts

@@ -0,0 +1,17 @@
+export declare const extractMinorVersion: (version: string) => string;
+/**
+ * Creates preamble text from a version number. The preamble text is used in stencil.config.ts and inserts a comment at the top of the generated bundles.
+ * The preamble text contains the version number and a link to the license.
+ * The version number is typically extracted from the package.json file.
+ * @example
+ * ```ts
+ * const preamble = getPreamble("4.18.2-beta.1");
+ * console.log(preamble);
+ * // All material copyright Esri, All Rights Reserved, unless otherwise specified.
+ * // See https://js.arcgis.com/4.18/esri/copyright.txt for details.
+ * // v4.18.2-beta.1
+ * ```
+ * @param version the version number, typically coming from package.json.
+ * @returns a string containing the preamble text.
+ */
+export declare const getPreamble: (version: string) => string;

package/dist/preamble.d.ts

@@ -0,0 +1,17 @@
+export declare const extractMinorVersion: (version: string) => string;
+/**
+ * Creates preamble text from a version number. The preamble text is used in stencil.config.ts and inserts a comment at the top of the generated bundles.
+ * The preamble text contains the version number and a link to the license.
+ * The version number is typically extracted from the package.json file.
+ * @example
+ * ```ts
+ * const preamble = getPreamble("4.18.2-beta.1");
+ * console.log(preamble);
+ * // All material copyright Esri, All Rights Reserved, unless otherwise specified.
+ * // See https://js.arcgis.com/4.18/esri/copyright.txt for details.
+ * // v4.18.2-beta.1
+ * ```
+ * @param version the version number, typically coming from package.json.
+ * @returns a string containing the preamble text.
+ */
+export declare const getPreamble: (version: string) => string;

package/dist/strings.d.cts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ * @param value The string to quote
+ * @returns The quoted string
+ */
+export declare function quoteString(value: string): string;
+/**
+ * Create a filter expression from a filter word.
+ * @param filterWord The filter word to create the expression from.
+ * @returns The filter expression.
+ */
+export declare function createFilterExpression(filterWord: string): RegExp;
+/**
+ * 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.
+ * @param message The string to replace values in.
+ * @param values The values to replace in the string.
+ * @returns The string with the values replaced.
+ */
+export declare function setValuesInString(message: string | null | undefined, values?: Record<string, string>): string;
+/**
+ * Add LTR marks to a string to ensure it is displayed as LTR.
+ * @param value The string to add LTR marks to.
+ * @returns The string with LTR marks.
+ */
+export declare function addLTRMark(value: string | undefined): string;

package/dist/strings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ * @param value The string to quote
+ * @returns The quoted string
+ */
+export declare function quoteString(value: string): string;
+/**
+ * Create a filter expression from a filter word.
+ * @param filterWord The filter word to create the expression from.
+ * @returns The filter expression.
+ */
+export declare function createFilterExpression(filterWord: string): RegExp;
+/**
+ * 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.
+ * @param message The string to replace values in.
+ * @param values The values to replace in the string.
+ * @returns The string with the values replaced.
+ */
+export declare function setValuesInString(message: string | null | undefined, values?: Record<string, string>): string;
+/**
+ * Add LTR marks to a string to ensure it is displayed as LTR.
+ * @param value The string to add LTR marks to.
+ * @returns The string with LTR marks.
+ */
+export declare function addLTRMark(value: string | undefined): string;

package/dist/tests/utils.d.cts

@@ -0,0 +1 @@
+export declare function captureConsoleErrors(): unknown[][];

package/dist/tests/utils.d.ts

@@ -0,0 +1 @@
+export declare function captureConsoleErrors(): unknown[][];

package/dist/text.d.cts

@@ -0,0 +1,7 @@
+/** Convert kebab-case string to PascalCase */
+export declare const kebabToPascal: (string: string) => string;
+/** Convert camelCase string to kebab-case */
+export declare const camelToKebab: (string: string) => string;
+export declare const capitalize: <T extends string>(string: T) => Capitalize<T>;
+export declare const uncapitalize: <T extends string>(string: T) => Uncapitalize<T>;
+export declare const camelToHuman: (string: string) => string;

package/dist/text.d.ts

@@ -0,0 +1,7 @@
+/** Convert kebab-case string to PascalCase */
+export declare const kebabToPascal: (string: string) => string;
+/** Convert camelCase string to kebab-case */
+export declare const camelToKebab: (string: string) => string;
+export declare const capitalize: <T extends string>(string: T) => Capitalize<T>;
+export declare const uncapitalize: <T extends string>(string: T) => Uncapitalize<T>;
+export declare const camelToHuman: (string: string) => string;

package/dist/timeouts.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Like setTimeout(), but does not advance the clock if the program is
+ * stopped on a debugger breakpoint.
+ *
+ * @see https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/60405
+ */
+export declare function devToolsAwareTimeout(callback: () => void, timeout: number): ReturnType<typeof setInterval>;

package/dist/timeouts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Like setTimeout(), but does not advance the clock if the program is
+ * stopped on a debugger breakpoint.
+ *
+ * @see https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/60405
+ */
+export declare function devToolsAwareTimeout(callback: () => void, timeout: number): ReturnType<typeof setInterval>;

package/dist/type-guards.d.cts

@@ -0,0 +1,12 @@
+/**
+ * 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 function isNotNull<T>(item: T | null): item is T;
+/**
+ * Safe guard to ensure that an item is not undefined.
+ * @param item The item to check.
+ * @returns Returns true if the item is not undefined.
+ */
+export declare function isNotUndefined<T>(item: T | undefined): item is T;

package/dist/type-guards.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 function isNotNull<T>(item: T | null): item is T;
+/**
+ * Safe guard to ensure that an item is not undefined.
+ * @param item The item to check.
+ * @returns Returns true if the item is not undefined.
+ */
+export declare function isNotUndefined<T>(item: T | undefined): item is T;

package/dist/types.d.cts

@@ -0,0 +1,30 @@
+export type Nil = null | undefined;
+export type IHandle = {
+    remove: () => void;
+};
+/**
+ * Identity function - returns back the first parameter
+ *
+ * Useful when providing a "mapping function" is required, but you have no need
+ * to change the value
+ */
+export declare const identity: <T>(value: T) => T;
+/**
+ * Get back a type whose keys are all marked as mutable (no longer "readonly")
+ *
+ * It's a best practice to mark all keys as readonly by default in all the
+ * interfaces and types you create. Benefits:
+ * - Explicitly documents that a given key won't be modified/should not be
+ *   modified
+ * - Favors more declarative and functional style programming
+ * - Helps prevent bugs related to mutation unexpectedly affecting other places
+ *   that held a reference to the same object
+ *
+ * Your function could return a type like "ResolvedConfig", that has all keys
+ * marked as readonly. But inside the function you may wish to modify some of
+ * the keys while creating the object - casting the object to
+ * `Writable<ResolvedConfig>` helps with that
+ */
+export type Writable<T> = {
+    -readonly [k in keyof T]: T[k];
+};

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export type Nil = null | undefined;
+export type IHandle = {
+    remove: () => void;
+};
+/**
+ * Identity function - returns back the first parameter
+ *
+ * Useful when providing a "mapping function" is required, but you have no need
+ * to change the value
+ */
+export declare const identity: <T>(value: T) => T;
+/**
+ * Get back a type whose keys are all marked as mutable (no longer "readonly")
+ *
+ * It's a best practice to mark all keys as readonly by default in all the
+ * interfaces and types you create. Benefits:
+ * - Explicitly documents that a given key won't be modified/should not be
+ *   modified
+ * - Favors more declarative and functional style programming
+ * - Helps prevent bugs related to mutation unexpectedly affecting other places
+ *   that held a reference to the same object
+ *
+ * Your function could return a type like "ResolvedConfig", that has all keys
+ * marked as readonly. But inside the function you may wish to modify some of
+ * the keys while creating the object - casting the object to
+ * `Writable<ResolvedConfig>` helps with that
+ */
+export type Writable<T> = {
+    -readonly [k in keyof T]: T[k];
+};

package/dist/ui.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Allows to debounce a function.
+ * @template F Function type that should extend a function with any parameters and a return type.
+ * @param func Function to be debounced
+ * @param waitFor Debounce time in milliseconds
+ * @returns Returns a function that can be called to debounce the given function.
+ */
+export declare function debounce<F extends (...args: Parameters<F>) => ReturnType<F>>(func: F, waitFor?: number): (...args: Parameters<F>) => void;

package/dist/ui.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Allows to debounce a function.
+ * @template F Function type that should extend a function with any parameters and a return type.
+ * @param func Function to be debounced
+ * @param waitFor Debounce time in milliseconds
+ * @returns Returns a function that can be called to debounce the given function.
+ */
+export declare function debounce<F extends (...args: Parameters<F>) => ReturnType<F>>(func: F, waitFor?: number): (...args: Parameters<F>) => void;

package/dist/url.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Compares two url strings for their origin and returns true if they have the same origin.
+ * @param url1 First url string
+ * @param url2 Second url string
+ * @param ignoreProtocol Indicates if protocol comparison should be ignored
+ * @returns True if the two url strings have the same origin
+ */
+export declare function hasSameOrigin(url1: string | null | undefined, url2: string | null | undefined, ignoreProtocol?: boolean): boolean;
+/**
+ * Tests if a url string is a URL or not.
+ * @param url The url string to test
+ * @returns True if the string is a URL.
+ */
+export declare function isURL(url: string): boolean;

package/dist/url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compares two url strings for their origin and returns true if they have the same origin.
+ * @param url1 First url string
+ * @param url2 Second url string
+ * @param ignoreProtocol Indicates if protocol comparison should be ignored
+ * @returns True if the two url strings have the same origin
+ */
+export declare function hasSameOrigin(url1: string | null | undefined, url2: string | null | undefined, ignoreProtocol?: boolean): boolean;
+/**
+ * Tests if a url string is a URL or not.
+ * @param url The url string to test
+ * @returns True if the string is a URL.
+ */
+export declare function isURL(url: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/components-utils",
-  "version": "4.33.0-next.9",
+  "version": "4.33.0-next.90",
   "description": "Collection of common internal patterns and utilities for ArcGIS Maps SDK for JavaScript components.",
   "homepage": "https://developers.arcgis.com/javascript/latest/",
   "sideEffects": false,