@arcgis/toolkit 5.0.0-next.9 → 5.0.0-next.90

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/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/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.d.cts

@@ -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

@@ -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/log/index.cjs

@@ -0,0 +1,69 @@
+"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 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.setEsriConfig = setEsriConfig;

package/dist/log/index.d.cts

@@ -0,0 +1,101 @@
+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/api-reference/esri-config.html#LogInterceptor}
+         */
+        interceptors?: ((level: LogLevel | "none", module: string, ...args: any[]) => void)[];
+    };
+};
+/**
+ * Workaround for setting {@link https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#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/api-reference/esri-config.html}
+ * @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.
+ *
+ * @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;
+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,101 @@
+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/api-reference/esri-config.html#LogInterceptor}
+         */
+        interceptors?: ((level: LogLevel | "none", module: string, ...args: any[]) => void)[];
+    };
+};
+/**
+ * Workaround for setting {@link https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#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/api-reference/esri-config.html}
+ * @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.
+ *
+ * @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;
+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,69 @@
+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 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,
+  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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/toolkit",
-  "version": "5.0.0-next.9",
+  "version": "5.0.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,
@@ -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",