@arcgis/toolkit 5.0.0-next.17 → 5.0.0-next.170

package/LICENSE.md

@@ -4,10 +4,14 @@ COPYRIGHT © Esri
 
 All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
 
-This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement. You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
+This material is licensed for use under the [Esri Master License Agreement (MLA)](https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf), and is bound by the terms of that agreement.
+You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
 
-See use restrictions at http://www.esri.com/legal/pdfs/mla_e204_e300/english
+For additional information, contact:
+Environmental Systems Research Institute, Inc.
+Attn: Contracts and Legal Services Department
+380 New York Street
+Redlands, California, USA 92373
+USA
 
-For additional information, contact: Environmental Systems Research Institute, Inc. Attn: Contracts and Legal Services Department 380 New York Street Redlands, California, USA 92373 USA
-
-email: contracts@esri.com
+email: legal@esri.com

package/README.md

@@ -8,6 +8,5 @@ It is not intended to be used directly, but rather used as a dependency by other
 
 ## License
 
-COPYRIGHT © Esri
-
-This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package.
+This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.0/LICENSE.txt.
+For third party notices, see https://js.arcgis.com/5.0/third-party-notices.txt.

package/dist/array/index.cjs

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const mappedFind = (array, callback) => {
-  for (let i = 0; i < array.length; i++) {
+  const length = array.length;
+  for (let i = 0; i < length; ++i) {
     const value = callback(array[i], i);
     if (value != null) {
       return value ?? void 0;

package/dist/array/index.d.cts

@@ -1,4 +1,4 @@
-import { nil } from '../type';
+import { nil } from '../type/index.ts';
 /**
  * A combination of map and find.
  * Find a value in an array, and return its mapped variant.

package/dist/array/index.d.ts

@@ -1,4 +1,4 @@
-import { nil } from '../type';
+import { nil } from '../type/index.ts';
 /**
  * A combination of map and find.
  * Find a value in an array, and return its mapped variant.

package/dist/array/index.js

@@ -1,5 +1,6 @@
 const mappedFind = (array, callback) => {
-  for (let i = 0; i < array.length; i++) {
+  const length = array.length;
+  for (let i = 0; i < length; ++i) {
     const value = callback(array[i], i);
     if (value != null) {
       return value ?? void 0;

package/dist/dom/index.cjs

@@ -31,7 +31,7 @@ function getSlotAssignedElements(slot, selector) {
 }
 const classes = (...classes2) => {
   const effectiveClasses = [];
-  for (let i = 0; i < classes2.length; i++) {
+  for (let i = 0; i < classes2.length; ++i) {
     const arg = classes2[i];
     if (typeof arg === "string") {
       effectiveClasses.push(arg);

package/dist/dom/index.d.cts

@@ -1,5 +1,5 @@
-import { nil } from '../type';
-export * from './slots';
+import { nil } from '../type/index.ts';
+export * from './slots.ts';
 /**
  * Combine multiple class names into a single string.
  *
@@ -76,7 +76,7 @@ export declare function unsafeGetCalciteModeName(el: HTMLElement): "dark" | "lig
  * expected to respect what was set by the consumer.
  *
  * @remarks
- * Prefer [useDirection()](https://qawebgis.esri.com/components/lumina/controllers/useDirection)
+ * 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";

package/dist/dom/index.d.ts

@@ -1,5 +1,5 @@
-import { nil } from '../type';
-export * from './slots';
+import { nil } from '../type/index.ts';
+export * from './slots.ts';
 /**
  * Combine multiple class names into a single string.
  *
@@ -76,7 +76,7 @@ export declare function unsafeGetCalciteModeName(el: HTMLElement): "dark" | "lig
  * expected to respect what was set by the consumer.
  *
  * @remarks
- * Prefer [useDirection()](https://qawebgis.esri.com/components/lumina/controllers/useDirection)
+ * 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";

package/dist/dom/index.js

@@ -29,7 +29,7 @@ function getSlotAssignedElements(slot, selector) {
 }
 const classes = (...classes2) => {
   const effectiveClasses = [];
-  for (let i = 0; i < classes2.length; i++) {
+  for (let i = 0; i < classes2.length; ++i) {
     const arg = classes2[i];
     if (typeof arg === "string") {
       effectiveClasses.push(arg);

package/dist/dom/slots.d.cts

@@ -14,7 +14,7 @@ export declare function slotChangeHasContent(event: Event): boolean;
  * Returns a string of textContent if the target `slot` element from the `onSlotchange` event has any text content.
  *
  * @param event The event.
- * @returns {string} The slots text.
+ * @returns The slots text.
  *
  * @example
  * ```tsx
@@ -73,9 +73,9 @@ export declare function slotChangeHasAssignedElement(event: Event): boolean;
 /**
  * Returns the assigned elements on a `slot` element from the `onSlotchange` 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.
+ * @param event The event.
+ * @param selector The CSS selector string to filter the returned elements by.
+ * @returns An array of elements.
  *
  * @example
  * ```tsx
@@ -86,8 +86,8 @@ export declare function slotChangeGetAssignedElements<T extends Element>(event:
 /**
  * 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.
+ * @param slot The slot element.
+ * @param selector CSS selector string to filter the returned elements by.
+ * @returns An array of elements.
  */
 export declare function getSlotAssignedElements<T extends Element>(slot: HTMLSlotElement, selector?: string): T[];

package/dist/dom/slots.d.ts

@@ -14,7 +14,7 @@ export declare function slotChangeHasContent(event: Event): boolean;
  * Returns a string of textContent if the target `slot` element from the `onSlotchange` event has any text content.
  *
  * @param event The event.
- * @returns {string} The slots text.
+ * @returns The slots text.
  *
  * @example
  * ```tsx
@@ -73,9 +73,9 @@ export declare function slotChangeHasAssignedElement(event: Event): boolean;
 /**
  * Returns the assigned elements on a `slot` element from the `onSlotchange` 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.
+ * @param event The event.
+ * @param selector The CSS selector string to filter the returned elements by.
+ * @returns An array of elements.
  *
  * @example
  * ```tsx
@@ -86,8 +86,8 @@ export declare function slotChangeGetAssignedElements<T extends Element>(event:
 /**
  * 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.
+ * @param slot The slot element.
+ * @param selector CSS selector string to filter the returned elements by.
+ * @returns An array of elements.
  */
 export declare function getSlotAssignedElements<T extends Element>(slot: HTMLSlotElement, selector?: string): T[];

package/dist/error/index.d.cts

@@ -10,12 +10,12 @@
  * - `process.env.NODE_ENV === "development"`
  * - `process.env.NODE_ENV === "test"`
  *
- * [Documentation](https://qawebgis.esri.com/components/lumina/publishing#internal-esri-environment)
+ * [Documentation](https://webgis.esri.com/references/lumina/publishing#internal-esri-environment)
  *
  * @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
+ * https://webgis.esri.com/references/lumina/publishing#bundling-code-conditionally
  */
 export declare const isEsriInternalEnv: () => boolean;
 /**

package/dist/error/index.d.ts

@@ -10,12 +10,12 @@
  * - `process.env.NODE_ENV === "development"`
  * - `process.env.NODE_ENV === "test"`
  *
- * [Documentation](https://qawebgis.esri.com/components/lumina/publishing#internal-esri-environment)
+ * [Documentation](https://webgis.esri.com/references/lumina/publishing#internal-esri-environment)
  *
  * @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
+ * https://webgis.esri.com/references/lumina/publishing#bundling-code-conditionally
  */
 export declare const isEsriInternalEnv: () => boolean;
 /**

package/dist/intl/index.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const dom_index = require("../dom/index.cjs");
+const log_index = require("../log/index.cjs");
 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".split(
   ","
 );
@@ -40,12 +41,14 @@ const fetchBundle = async (locale, path) => {
     if (process.env.NODE_ENV !== "production") {
       const is404ViteFallback = String(error).includes(`Unexpected token '<', "<!doctype "... is not valid JSON`);
       if (is404ViteFallback) {
-        console.error(`[404] Localization strings not found at ${filePath}`);
+        log_index.log("error", "intl", `Localization strings not found at ${filePath}`);
       } else {
-        console.error(`Error fetching localization strings at ${filePath}`, error);
+        log_index.log("error", "intl", `Error fetching localization strings at ${filePath}`, { detail: { error } });
       }
     } else {
-      console.error(error);
+      log_index.log("error", "intl", `An unknown error occurred while fetching localization strings at ${filePath}`, {
+        detail: { error }
+      });
     }
     return {};
   }
@@ -81,7 +84,9 @@ const startLocaleObserver = (element, getAssetsPath, onUpdated, assetName) => {
       onUpdated(newResult);
     }
     result = newResult;
-  }).catch(console.error);
+  }).catch((error) => {
+    log_index.log("error", "intl", "Error updating component locale state", { detail: { error } });
+  });
   queueMicrotask(callback);
   return dom_index.observeAncestorsMutation(element, ["lang"], callback);
 };

package/dist/intl/index.d.cts

@@ -2,7 +2,7 @@ declare const supportedLocalesArray: ["ar", "bg", "bs", "ca", "cs", "da", "de",
 /**
  * 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 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
  */
@@ -23,7 +23,7 @@ export declare const defaultLocale = "en";
  *
  * @remarks
  * Rather than using this function directly, prefer the
- * [useT9n()](https://qawebgis.esri.com/components/lumina/controllers/useT9n)
+ * [useT9n()](https://webgis.esri.com/references/lumina/controllers/useT9n)
  * controller.
  *
  * @remarks
@@ -39,7 +39,7 @@ export declare const defaultLocale = "en";
  * );
  * ```
  *
- * @see [Lumina asset handling](https://qawebgis.esri.com/components/lumina/assets)
+ * @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>;
 /**
@@ -55,7 +55,7 @@ export interface GenericT9nStrings {
  *
  * @returns an object with the `lang` and `t9nLocale` properties.
  *
- * @see [lang vs t9nLocale](https://qawebgis.esri.com/components/lumina/controllers/useT9n#difference-between-lang-and-t9nlocale).
+ * @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;
@@ -103,7 +103,7 @@ export interface LocaleObserverResult<Strings extends GenericT9nStrings = Generi
  *
  * @remarks
  * Rather than using this function directly, prefer the
- * [useT9n()](https://qawebgis.esri.com/components/lumina/controllers/useT9n)
+ * [useT9n()](https://webgis.esri.com/references/lumina/controllers/useT9n)
  * controller.
  *
  * @example

package/dist/intl/index.d.ts

@@ -2,7 +2,7 @@ declare const supportedLocalesArray: ["ar", "bg", "bs", "ca", "cs", "da", "de",
 /**
  * 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 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
  */
@@ -23,7 +23,7 @@ export declare const defaultLocale = "en";
  *
  * @remarks
  * Rather than using this function directly, prefer the
- * [useT9n()](https://qawebgis.esri.com/components/lumina/controllers/useT9n)
+ * [useT9n()](https://webgis.esri.com/references/lumina/controllers/useT9n)
  * controller.
  *
  * @remarks
@@ -39,7 +39,7 @@ export declare const defaultLocale = "en";
  * );
  * ```
  *
- * @see [Lumina asset handling](https://qawebgis.esri.com/components/lumina/assets)
+ * @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>;
 /**
@@ -55,7 +55,7 @@ export interface GenericT9nStrings {
  *
  * @returns an object with the `lang` and `t9nLocale` properties.
  *
- * @see [lang vs t9nLocale](https://qawebgis.esri.com/components/lumina/controllers/useT9n#difference-between-lang-and-t9nlocale).
+ * @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;
@@ -103,7 +103,7 @@ export interface LocaleObserverResult<Strings extends GenericT9nStrings = Generi
  *
  * @remarks
  * Rather than using this function directly, prefer the
- * [useT9n()](https://qawebgis.esri.com/components/lumina/controllers/useT9n)
+ * [useT9n()](https://webgis.esri.com/references/lumina/controllers/useT9n)
  * controller.
  *
  * @example

package/dist/intl/index.js

@@ -1,4 +1,5 @@
 import { getElementAttribute, observeAncestorsMutation } from "../dom/index.js";
+import { log } from "../log/index.js";
 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".split(
   ","
 );
@@ -38,12 +39,14 @@ const fetchBundle = async (locale, path) => {
     if (process.env.NODE_ENV !== "production") {
       const is404ViteFallback = String(error).includes(`Unexpected token '<', "<!doctype "... is not valid JSON`);
       if (is404ViteFallback) {
-        console.error(`[404] Localization strings not found at ${filePath}`);
+        log("error", "intl", `Localization strings not found at ${filePath}`);
       } else {
-        console.error(`Error fetching localization strings at ${filePath}`, error);
+        log("error", "intl", `Error fetching localization strings at ${filePath}`, { detail: { error } });
       }
     } else {
-      console.error(error);
+      log("error", "intl", `An unknown error occurred while fetching localization strings at ${filePath}`, {
+        detail: { error }
+      });
     }
     return {};
   }
@@ -79,7 +82,9 @@ const startLocaleObserver = (element, getAssetsPath, onUpdated, assetName) => {
       onUpdated(newResult);
     }
     result = newResult;
-  }).catch(console.error);
+  }).catch((error) => {
+    log("error", "intl", "Error updating component locale state", { detail: { error } });
+  });
   queueMicrotask(callback);
   return observeAncestorsMutation(element, ["lang"], callback);
 };

package/dist/log/index.cjs

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const loggedMessages = /* @__PURE__ */ new Set();
+let esriConfig;
+const setEsriConfig = (config) => {
+  esriConfig = config;
+};
+const getContextString = (context) => {
+  if (typeof context === "string") {
+    return context;
+  }
+  if ("el" in context) {
+    return context.el.localName;
+  }
+  if ("localName" in context) {
+    return context.localName;
+  }
+  return context.declaredClass;
+};
+const log = (level, context, message, options) => {
+  const contextString = getContextString(context);
+  if (options?.once) {
+    const key = `${level}${contextString}${message}`;
+    if (loggedMessages.has(key)) {
+      return;
+    }
+    loggedMessages.add(key);
+  }
+  let memorySafeDetail;
+  if (options?.detail) {
+    memorySafeDetail = {};
+    for (const [key, value] of Object.entries(options.detail)) {
+      if ((typeof value === "object" || typeof value === "function") && value !== null) {
+        const weakRefValue = new WeakRef(value);
+        Object.defineProperty(memorySafeDetail, key, {
+          get() {
+            return weakRefValue.deref();
+          }
+        });
+      } else {
+        memorySafeDetail[key] = value;
+      }
+    }
+    esriConfig?.log.interceptors?.forEach(
+      (interceptor) => interceptor(level, contextString, message, memorySafeDetail)
+    );
+    console[level](`[${contextString}]: ${message}`, memorySafeDetail);
+  } else {
+    esriConfig?.log.interceptors?.forEach((interceptor) => interceptor(level, contextString, message));
+    console[level](`[${contextString}]: ${message}`);
+  }
+};
+const rethrowError = (context) => {
+  const prefix = `[${getContextString(context)}] `;
+  return (error) => {
+    const errorToRethrow = error instanceof Error && error.message ? error : new Error(String(error));
+    errorToRethrow.message = `${prefix}${errorToRethrow.message}`;
+    setTimeout(() => {
+      throw error;
+    });
+  };
+};
+const composeMissingPropertyMessage = (property) => (
+  //#endregion composeMissingPropertyMessage
+  `The property \`${property.toString()}\` is required but missing.`
+);
+const composeEmptyPropertyMessage = (property) => (
+  //#endregion composeEmptyPropertyMessage
+  `The property \`${property.toString()}\` is empty but must have at least one element.`
+);
+const logDeprecatedProperty = (context, oldName, newName, options) => (
+  //#endregion logDeprecatedProperty
+  log("warn", context, `\`${oldName.toString()}\` is deprecated. Use \`${newName.toString()}\` instead.`, options)
+);
+exports.composeEmptyPropertyMessage = composeEmptyPropertyMessage;
+exports.composeMissingPropertyMessage = composeMissingPropertyMessage;
+exports.log = log;
+exports.logDeprecatedProperty = logDeprecatedProperty;
+exports.rethrowError = rethrowError;
+exports.setEsriConfig = setEsriConfig;

package/dist/log/index.d.cts

@@ -0,0 +1,128 @@
+export type LogLevel = "error" | "info" | "warn";
+type CustomElementLike = {
+    el: {
+        localName: string;
+    };
+} | {
+    localName: string;
+};
+type AccessorLike = {
+    declaredClass: string;
+};
+export type LogContext = AccessorLike | CustomElementLike | string;
+type LogOptions = {
+    /** Whether the message should only be logged once. */
+    once?: boolean;
+    /** Additional objects to log after `message`. Use this to avoid memory leaks when logging objects to the console. Each object value will be automatically wrapped in a `WeakRef` before logging so it can be garbage-collected. */
+    detail?: Record<string, unknown>;
+};
+type EsriConfig = {
+    log: {
+        /**
+         * @link {https://developers.arcgis.com/javascript/latest/references/core/config/#LogInterceptor}
+         */
+        interceptors?: ((level: LogLevel | "none", module: string, ...args: any[]) => void)[];
+    };
+};
+/**
+ * Workaround for setting {@link https://developers.arcgis.com/javascript/latest/references/core/config/#log log interceptors} and maintaining compatibility with {@link https://devtopia.esri.com/WebGIS/arcgis-websceneviewer-app/blob/8f0a1bbcf12d1193134d94589d9e187f0afa72fa/src/js/support/ApiLoggerInstrumentation.ts#L17 js-api's interceptor usage}.
+ * @see {@link https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/74935}
+ * @param config {@link https://developers.arcgis.com/javascript/latest/references/core/config/}
+ * @example
+ * ```ts
+ * // IMPORTANT: do this only in config.ts or another early-loaded module
+ * import esriConfig from "@arcgis/core/config.js";
+ * import { setEsriConfig } from "@arcgis/toolkit/log";
+ *
+ * setEsriConfig(esriConfig);
+ *
+ * // either here or in another file, you can add your interceptors
+ * // and they will be respected when log is called later on
+ * esriConfig.log.interceptors?.push(yourInterceptor);
+ * ```
+ */
+export declare const setEsriConfig: (config: EsriConfig) => void;
+/**
+ * Helper utility for logging messages in a consistent manner.
+ *
+ * @param level The log level
+ * @param context The context of the log message (e.g., `this` inside a Lit-like component, or just a custom string)
+ * @param message A custom message to log
+ * @param options Additional options for logging, such as to provide a context object
+ *
+ * @see [setEsriConfig](#setEsriConfig)
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * log("error", this, "message to log");
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional usage
+ * log("warn", this, "message to log", {
+ *   once: true,
+ *   detail: { object1, object2 }
+ * });
+ */
+export declare const log: (level: LogLevel, context: LogContext, message: string, options?: LogOptions) => void;
+/**
+ * Rethrows an error and prepends context information to the error message. The error is
+ * thrown asynchronously to avoid interrupting the current execution stack, so it cannot be caught
+ * with `try/catch` and will bubble to the global object.
+ * @param context From where the error is being thrown (e.g., `this` inside a Lit-like component, or just a custom string)
+ * @returns A function that can be used in `try-catch`/`.catch` to rethrow an error
+ *
+ * @example
+ * ```ts
+ * try {
+ *   functionThatMightThrow();
+ * } catch (error) {
+ *   rethrowError(this)(error);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * promise.then().catch(rethrowError("context string"));
+ * ```
+ */
+export declare const rethrowError: (context: LogContext) => ((error: unknown) => void);
+type LogContextOrObject = Exclude<LogContext, string> | object;
+type InferPropertyType<T extends LogContextOrObject> = [object] extends [T] ? string : keyof T;
+/**
+ * Returns a string that can be used in log messages for missing required properties.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is required but missing."
+ * composeMissingPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeMissingPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeMissingPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Returns a string that can be used in log messages for empty required arrays.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is empty but must have at least one element."
+ * composeEmptyPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeEmptyPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeEmptyPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Logs a warning message for deprecated object properties.
+ * @example
+ * ```ts
+ * logDeprecatedProperty(this, "oldName", "newName", {
+ *   once: true,
+ * });
+ * ```
+ */
+export declare const logDeprecatedProperty: <T extends LogContext>(context: T, oldName: keyof T, newName: keyof T, options?: LogOptions) => ReturnType<typeof log>;
+export {};

package/dist/log/index.d.ts

@@ -0,0 +1,128 @@
+export type LogLevel = "error" | "info" | "warn";
+type CustomElementLike = {
+    el: {
+        localName: string;
+    };
+} | {
+    localName: string;
+};
+type AccessorLike = {
+    declaredClass: string;
+};
+export type LogContext = AccessorLike | CustomElementLike | string;
+type LogOptions = {
+    /** Whether the message should only be logged once. */
+    once?: boolean;
+    /** Additional objects to log after `message`. Use this to avoid memory leaks when logging objects to the console. Each object value will be automatically wrapped in a `WeakRef` before logging so it can be garbage-collected. */
+    detail?: Record<string, unknown>;
+};
+type EsriConfig = {
+    log: {
+        /**
+         * @link {https://developers.arcgis.com/javascript/latest/references/core/config/#LogInterceptor}
+         */
+        interceptors?: ((level: LogLevel | "none", module: string, ...args: any[]) => void)[];
+    };
+};
+/**
+ * Workaround for setting {@link https://developers.arcgis.com/javascript/latest/references/core/config/#log log interceptors} and maintaining compatibility with {@link https://devtopia.esri.com/WebGIS/arcgis-websceneviewer-app/blob/8f0a1bbcf12d1193134d94589d9e187f0afa72fa/src/js/support/ApiLoggerInstrumentation.ts#L17 js-api's interceptor usage}.
+ * @see {@link https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/74935}
+ * @param config {@link https://developers.arcgis.com/javascript/latest/references/core/config/}
+ * @example
+ * ```ts
+ * // IMPORTANT: do this only in config.ts or another early-loaded module
+ * import esriConfig from "@arcgis/core/config.js";
+ * import { setEsriConfig } from "@arcgis/toolkit/log";
+ *
+ * setEsriConfig(esriConfig);
+ *
+ * // either here or in another file, you can add your interceptors
+ * // and they will be respected when log is called later on
+ * esriConfig.log.interceptors?.push(yourInterceptor);
+ * ```
+ */
+export declare const setEsriConfig: (config: EsriConfig) => void;
+/**
+ * Helper utility for logging messages in a consistent manner.
+ *
+ * @param level The log level
+ * @param context The context of the log message (e.g., `this` inside a Lit-like component, or just a custom string)
+ * @param message A custom message to log
+ * @param options Additional options for logging, such as to provide a context object
+ *
+ * @see [setEsriConfig](#setEsriConfig)
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * log("error", this, "message to log");
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional usage
+ * log("warn", this, "message to log", {
+ *   once: true,
+ *   detail: { object1, object2 }
+ * });
+ */
+export declare const log: (level: LogLevel, context: LogContext, message: string, options?: LogOptions) => void;
+/**
+ * Rethrows an error and prepends context information to the error message. The error is
+ * thrown asynchronously to avoid interrupting the current execution stack, so it cannot be caught
+ * with `try/catch` and will bubble to the global object.
+ * @param context From where the error is being thrown (e.g., `this` inside a Lit-like component, or just a custom string)
+ * @returns A function that can be used in `try-catch`/`.catch` to rethrow an error
+ *
+ * @example
+ * ```ts
+ * try {
+ *   functionThatMightThrow();
+ * } catch (error) {
+ *   rethrowError(this)(error);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * promise.then().catch(rethrowError("context string"));
+ * ```
+ */
+export declare const rethrowError: (context: LogContext) => ((error: unknown) => void);
+type LogContextOrObject = Exclude<LogContext, string> | object;
+type InferPropertyType<T extends LogContextOrObject> = [object] extends [T] ? string : keyof T;
+/**
+ * Returns a string that can be used in log messages for missing required properties.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is required but missing."
+ * composeMissingPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeMissingPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeMissingPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Returns a string that can be used in log messages for empty required arrays.
+ * @param property The name of the required property
+ * @example
+ * ```ts
+ * // returns "The property `x` is empty but must have at least one element."
+ * composeEmptyPropertyMessage<YourClass>("x");
+ * // you don't need to provide a generic type argument if you don't have one
+ * composeEmptyPropertyMessage("object.sub.property");
+ * ```
+ */
+export declare const composeEmptyPropertyMessage: <T extends LogContextOrObject = object>(property: InferPropertyType<T>) => string;
+/**
+ * Logs a warning message for deprecated object properties.
+ * @example
+ * ```ts
+ * logDeprecatedProperty(this, "oldName", "newName", {
+ *   once: true,
+ * });
+ * ```
+ */
+export declare const logDeprecatedProperty: <T extends LogContext>(context: T, oldName: keyof T, newName: keyof T, options?: LogOptions) => ReturnType<typeof log>;
+export {};

package/dist/log/index.js

@@ -0,0 +1,80 @@
+const loggedMessages = /* @__PURE__ */ new Set();
+let esriConfig;
+const setEsriConfig = (config) => {
+  esriConfig = config;
+};
+const getContextString = (context) => {
+  if (typeof context === "string") {
+    return context;
+  }
+  if ("el" in context) {
+    return context.el.localName;
+  }
+  if ("localName" in context) {
+    return context.localName;
+  }
+  return context.declaredClass;
+};
+const log = (level, context, message, options) => {
+  const contextString = getContextString(context);
+  if (options?.once) {
+    const key = `${level}${contextString}${message}`;
+    if (loggedMessages.has(key)) {
+      return;
+    }
+    loggedMessages.add(key);
+  }
+  let memorySafeDetail;
+  if (options?.detail) {
+    memorySafeDetail = {};
+    for (const [key, value] of Object.entries(options.detail)) {
+      if ((typeof value === "object" || typeof value === "function") && value !== null) {
+        const weakRefValue = new WeakRef(value);
+        Object.defineProperty(memorySafeDetail, key, {
+          get() {
+            return weakRefValue.deref();
+          }
+        });
+      } else {
+        memorySafeDetail[key] = value;
+      }
+    }
+    esriConfig?.log.interceptors?.forEach(
+      (interceptor) => interceptor(level, contextString, message, memorySafeDetail)
+    );
+    console[level](`[${contextString}]: ${message}`, memorySafeDetail);
+  } else {
+    esriConfig?.log.interceptors?.forEach((interceptor) => interceptor(level, contextString, message));
+    console[level](`[${contextString}]: ${message}`);
+  }
+};
+const rethrowError = (context) => {
+  const prefix = `[${getContextString(context)}] `;
+  return (error) => {
+    const errorToRethrow = error instanceof Error && error.message ? error : new Error(String(error));
+    errorToRethrow.message = `${prefix}${errorToRethrow.message}`;
+    setTimeout(() => {
+      throw error;
+    });
+  };
+};
+const composeMissingPropertyMessage = (property) => (
+  //#endregion composeMissingPropertyMessage
+  `The property \`${property.toString()}\` is required but missing.`
+);
+const composeEmptyPropertyMessage = (property) => (
+  //#endregion composeEmptyPropertyMessage
+  `The property \`${property.toString()}\` is empty but must have at least one element.`
+);
+const logDeprecatedProperty = (context, oldName, newName, options) => (
+  //#endregion logDeprecatedProperty
+  log("warn", context, `\`${oldName.toString()}\` is deprecated. Use \`${newName.toString()}\` instead.`, options)
+);
+export {
+  composeEmptyPropertyMessage,
+  composeMissingPropertyMessage,
+  log,
+  logDeprecatedProperty,
+  rethrowError,
+  setEsriConfig
+};

package/dist/predicate/index.d.cts

@@ -1,4 +1,4 @@
-import { nil } from '../type';
+import { nil } from '../type/index.ts';
 /**
  * Safeguard to ensure that an item is not undefined.
  * @param item The item to check.

package/dist/predicate/index.d.ts

@@ -1,4 +1,4 @@
-import { nil } from '../type';
+import { nil } from '../type/index.ts';
 /**
  * Safeguard to ensure that an item is not undefined.
  * @param item The item to check.

package/dist/string/index.cjs

@@ -72,9 +72,7 @@ const getMinorVersion = (version) => {
 };
 const getPreamble = (version) => (
   //#endregion getPreamble
-  `All material copyright Esri, All Rights Reserved, unless otherwise specified.
-See https://js.arcgis.com/${getMinorVersion(version)}/esri/copyright.txt for details.
-v${version}`
+  `COPYRIGHT Esri - https://js.arcgis.com/${getMinorVersion(version)}/LICENSE.txt`
 );
 const setValuesInString = (message, values = {}) => (message ?? "").replace(/\{(?<valueName>.*?)\}/gu, (match, valueName) => values[valueName] ?? match);
 exports.addLtrMark = addLtrMark;

package/dist/string/index.d.cts

@@ -42,7 +42,7 @@ export declare const quoteString: (value: string) => string;
  * Create a filter expression from a filter word.
  *
  * @remarks Once browser support permits, use `RegExp.escape()` instead.
- * @todo DEPRECATE
+ * @privateRemarks TODO: DEPRECATE
  */
 export declare const createFilterExpression: (filterWord: string) => RegExp;
 /**
@@ -88,12 +88,12 @@ export declare const getMinorVersion: (version: string) => string;
  * notice at the top of a file.
  * The preamble text contains the version number and a link to the license.
  * The version number should normally come from package.json.
+ *
+ * @see https://webgis.esri.com/webgis/platform-guidelines/licensing
  * @example
  * ```ts
- * const preamble = getPreamble("4.34.0-next.123");
- * // All material copyright Esri, All Rights Reserved, unless otherwise specified.
- * // See https://js.arcgis.com/4.34/esri/copyright.txt for details.
- * // v4.34.0-next.123
+ * const preamble = getPreamble("5.0.1-next.456");
+ * // COPYRIGHT Esri - https://js.arcgis.com/5.0/LICENSE.txt
  * ```
  */
 export declare const getPreamble: (version: string) => string;
@@ -101,6 +101,6 @@ 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.
  *
- * @deprecated Import from https://next.gha.afd.arcgis.com/javascript/latest/api-reference/esri-intl.html#substitute instead
+ * @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;

package/dist/string/index.d.ts

@@ -42,7 +42,7 @@ export declare const quoteString: (value: string) => string;
  * Create a filter expression from a filter word.
  *
  * @remarks Once browser support permits, use `RegExp.escape()` instead.
- * @todo DEPRECATE
+ * @privateRemarks TODO: DEPRECATE
  */
 export declare const createFilterExpression: (filterWord: string) => RegExp;
 /**
@@ -88,12 +88,12 @@ export declare const getMinorVersion: (version: string) => string;
  * notice at the top of a file.
  * The preamble text contains the version number and a link to the license.
  * The version number should normally come from package.json.
+ *
+ * @see https://webgis.esri.com/webgis/platform-guidelines/licensing
  * @example
  * ```ts
- * const preamble = getPreamble("4.34.0-next.123");
- * // All material copyright Esri, All Rights Reserved, unless otherwise specified.
- * // See https://js.arcgis.com/4.34/esri/copyright.txt for details.
- * // v4.34.0-next.123
+ * const preamble = getPreamble("5.0.1-next.456");
+ * // COPYRIGHT Esri - https://js.arcgis.com/5.0/LICENSE.txt
  * ```
  */
 export declare const getPreamble: (version: string) => string;
@@ -101,6 +101,6 @@ 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.
  *
- * @deprecated Import from https://next.gha.afd.arcgis.com/javascript/latest/api-reference/esri-intl.html#substitute instead
+ * @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;

package/dist/string/index.js

@@ -70,9 +70,7 @@ const getMinorVersion = (version) => {
 };
 const getPreamble = (version) => (
   //#endregion getPreamble
-  `All material copyright Esri, All Rights Reserved, unless otherwise specified.
-See https://js.arcgis.com/${getMinorVersion(version)}/esri/copyright.txt for details.
-v${version}`
+  `COPYRIGHT Esri - https://js.arcgis.com/${getMinorVersion(version)}/LICENSE.txt`
 );
 const setValuesInString = (message, values = {}) => (message ?? "").replace(/\{(?<valueName>.*?)\}/gu, (match, valueName) => values[valueName] ?? match);
 export {

package/dist/type/index.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const typeTest = 0;
+exports.typeTest = typeTest;

package/dist/type/index.d.cts

@@ -13,3 +13,17 @@ export type IHandle = {
  * @deprecated Import type { nil } from `@arcgis/toolkit/type` instead
  */
 export type Nil = nil;
+/**
+ * A helper for doing TypeScript type tests.
+ * This complements the TypeScript's `satisfies` operator.
+ *
+ * See usage examples:
+ * https://webgis.esri.com/webgis/additional-resources/typescript-tips#use-satisfies-operator-for-type-tests
+ *
+ * During production end-application build, such type tests will be removed as
+ * they have no runtime impact.
+ *
+ * @privateRemarks
+ * Using `0` over `undefined` to take fewer bytes if minifier is disabled.
+ */
+export declare const typeTest: unknown;

package/dist/type/index.d.ts

@@ -13,3 +13,17 @@ export type IHandle = {
  * @deprecated Import type { nil } from `@arcgis/toolkit/type` instead
  */
 export type Nil = nil;
+/**
+ * A helper for doing TypeScript type tests.
+ * This complements the TypeScript's `satisfies` operator.
+ *
+ * See usage examples:
+ * https://webgis.esri.com/webgis/additional-resources/typescript-tips#use-satisfies-operator-for-type-tests
+ *
+ * During production end-application build, such type tests will be removed as
+ * they have no runtime impact.
+ *
+ * @privateRemarks
+ * Using `0` over `undefined` to take fewer bytes if minifier is disabled.
+ */
+export declare const typeTest: unknown;

package/dist/type/index.js

@@ -0,0 +1,4 @@
+const typeTest = 0;
+export {
+  typeTest
+};

package/dist/url/index.d.cts

@@ -13,6 +13,6 @@ export declare const hasSameOrigin: (url1: string | null | undefined, url2: stri
  * @returns True if the string is a URL.
  *
  * @remarks If browser support permits, use https://developer.mozilla.org/en-US/docs/Web/API/URL/parse_static instead
- * @todo DEPRECATE
+ * @privateRemarks TODO: DEPRECATE
  */
 export declare const isURL: (url: string) => boolean;

package/dist/url/index.d.ts

@@ -13,6 +13,6 @@ export declare const hasSameOrigin: (url1: string | null | undefined, url2: stri
  * @returns True if the string is a URL.
  *
  * @remarks If browser support permits, use https://developer.mozilla.org/en-US/docs/Web/API/URL/parse_static instead
- * @todo DEPRECATE
+ * @privateRemarks TODO: DEPRECATE
  */
 export declare const isURL: (url: string) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/toolkit",
-  "version": "5.0.0-next.17",
+  "version": "5.0.0-next.170",
   "description": "Collection of common internal patterns and utilities for ArcGIS Maps SDK for JavaScript components.",
   "homepage": "https://developers.arcgis.com/javascript/latest/",
   "sideEffects": false,
@@ -31,6 +31,11 @@
       "import": "./dist/intl/index.js",
       "require": "./dist/intl/index.cjs"
     },
+    "./log": {
+      "types": "./dist/log/index.d.ts",
+      "import": "./dist/log/index.js",
+      "require": "./dist/log/index.cjs"
+    },
     "./number": {
       "types": "./dist/number/index.d.ts",
       "import": "./dist/number/index.js",
@@ -52,7 +57,9 @@
       "require": "./dist/string/index.cjs"
     },
     "./type": {
-      "types": "./dist/type/index.d.ts"
+      "types": "./dist/type/index.d.ts",
+      "import": "./dist/type/index.js",
+      "require": "./dist/type/index.cjs"
     },
     "./url": {
       "types": "./dist/url/index.d.ts",