@arcgis/toolkit 5.1.0-next.9 → 5.1.0-next.91

package/dist/dom/index.cjs

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const log_index = require("../log/index.cjs");
 function slotChangeHasContent(event) {
   return slotChangeHasAssignedElement(event) || slotChangeHasTextContent(event);
 }
@@ -29,6 +30,33 @@ function getSlotAssignedElements(slot, selector) {
   });
   return selector ? assignedElements.filter((element) => element.matches(selector)) : assignedElements;
 }
+const allowedTags = ["arcgis-map", "arcgis-scene", "arcgis-link-chart"];
+function resolveReferenceElement(component, referenceElementString) {
+  const referenceElement = referenceElementString ?? component.referenceElement;
+  if (typeof referenceElement !== "string") {
+    return referenceElement ?? void 0;
+  }
+  const isComplexSelector = referenceElement.includes("#") || referenceElement.includes(".") || referenceElement.includes("[");
+  const rootNode = component.el.getRootNode();
+  const resolved = (isComplexSelector ? void 0 : rootNode.querySelector(`#${referenceElement}`)) ?? rootNode.querySelector(referenceElement) ?? (isComplexSelector ? void 0 : getClosestElement(component.el, `#${referenceElement}`)) ?? getClosestElement(component.el, referenceElement);
+  if (resolved == null) {
+    log_index.log(
+      "error",
+      component,
+      `Expected property \`referenceElement\` to resolve to an <arcgis-map>, <arcgis-scene>, or <arcgis-link-chart> element, but no element matched \`${referenceElement}\`.`
+    );
+    return void 0;
+  }
+  if (!allowedTags.includes(resolved.localName)) {
+    log_index.log(
+      "error",
+      component,
+      `Expected property \`referenceElement\` to point to an <arcgis-map>, <arcgis-scene>, or <arcgis-link-chart> element, but instead found <${resolved?.localName}>.`,
+      { detail: { referenceElement, resolved } }
+    );
+  }
+  return resolved ?? void 0;
+}
 const classes = (...classes2) => {
   const effectiveClasses = [];
   for (let i = 0; i < classes2.length; ++i) {
@@ -117,7 +145,7 @@ const getClosestElement = (base, selector) => {
     if (rootElement === globalThis.document) {
       return;
     }
-    currentElement = rootElement.host;
+    currentElement = rootElement?.host;
   }
   return;
 };
@@ -186,6 +214,7 @@ exports.getClosestElement = getClosestElement;
 exports.getElementAttribute = getElementAttribute;
 exports.getSlotAssignedElements = getSlotAssignedElements;
 exports.observeAncestorsMutation = observeAncestorsMutation;
+exports.resolveReferenceElement = resolveReferenceElement;
 exports.setFocusOnElement = setFocusOnElement;
 exports.slotChangeGetAssignedElements = slotChangeGetAssignedElements;
 exports.slotChangeGetAssignedNodes = slotChangeGetAssignedNodes;

package/dist/dom/index.d.cts

@@ -1,5 +1,6 @@
 import { nil } from '../type/index.ts';
 export * from './slots.ts';
+export * from './reference-element.ts';
 /**
  * Combine multiple class names into a single string.
  *

package/dist/dom/index.d.ts

@@ -1,5 +1,6 @@
 import { nil } from '../type/index.ts';
 export * from './slots.ts';
+export * from './reference-element.ts';
 /**
  * Combine multiple class names into a single string.
  *

package/dist/dom/index.js

@@ -1,3 +1,4 @@
+import { log } from "../log/index.js";
 function slotChangeHasContent(event) {
   return slotChangeHasAssignedElement(event) || slotChangeHasTextContent(event);
 }
@@ -27,6 +28,33 @@ function getSlotAssignedElements(slot, selector) {
   });
   return selector ? assignedElements.filter((element) => element.matches(selector)) : assignedElements;
 }
+const allowedTags = ["arcgis-map", "arcgis-scene", "arcgis-link-chart"];
+function resolveReferenceElement(component, referenceElementString) {
+  const referenceElement = referenceElementString ?? component.referenceElement;
+  if (typeof referenceElement !== "string") {
+    return referenceElement ?? void 0;
+  }
+  const isComplexSelector = referenceElement.includes("#") || referenceElement.includes(".") || referenceElement.includes("[");
+  const rootNode = component.el.getRootNode();
+  const resolved = (isComplexSelector ? void 0 : rootNode.querySelector(`#${referenceElement}`)) ?? rootNode.querySelector(referenceElement) ?? (isComplexSelector ? void 0 : getClosestElement(component.el, `#${referenceElement}`)) ?? getClosestElement(component.el, referenceElement);
+  if (resolved == null) {
+    log(
+      "error",
+      component,
+      `Expected property \`referenceElement\` to resolve to an <arcgis-map>, <arcgis-scene>, or <arcgis-link-chart> element, but no element matched \`${referenceElement}\`.`
+    );
+    return void 0;
+  }
+  if (!allowedTags.includes(resolved.localName)) {
+    log(
+      "error",
+      component,
+      `Expected property \`referenceElement\` to point to an <arcgis-map>, <arcgis-scene>, or <arcgis-link-chart> element, but instead found <${resolved?.localName}>.`,
+      { detail: { referenceElement, resolved } }
+    );
+  }
+  return resolved ?? void 0;
+}
 const classes = (...classes2) => {
   const effectiveClasses = [];
   for (let i = 0; i < classes2.length; ++i) {
@@ -115,7 +143,7 @@ const getClosestElement = (base, selector) => {
     if (rootElement === globalThis.document) {
       return;
     }
-    currentElement = rootElement.host;
+    currentElement = rootElement?.host;
   }
   return;
 };
@@ -185,6 +213,7 @@ export {
   getElementAttribute,
   getSlotAssignedElements,
   observeAncestorsMutation,
+  resolveReferenceElement,
   setFocusOnElement,
   slotChangeGetAssignedElements,
   slotChangeGetAssignedNodes,

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

@@ -0,0 +1,6 @@
+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/dom/reference-element.d.ts

@@ -0,0 +1,6 @@
+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.cjs

@@ -12,8 +12,10 @@ const supportedLocales = (
 const defaultLocale = "en";
 const localeEquivalencies = {
   //#region localeEquivalencies
-  // We use `pt-PT` as it will have the same translations as `pt`, which has no corresponding bundle
-  pt: "pt-PT",
+  // Locale equivalencies aligned with ArcGIS Maps SDK for JavaScript:
+  // https://developers.arcgis.com/javascript/latest/localization/#locale-support
+  // We resolve to `pt-BR` as it will have the same translations as `pt`, which has no corresponding bundle
+  pt: "pt-BR",
   // We support both 'nb' and 'no' (BCP 47) for Norwegian but only `no` has corresponding bundle
   nb: "no",
   // We support both 'nn' and 'no' (BCP 47) for Norwegian but only `no` has corresponding bundle

package/dist/intl/index.d.cts

@@ -65,6 +65,9 @@ export declare const getElementLocale: (element: HTMLElement) => {
  * 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.
  */

package/dist/intl/index.d.ts

@@ -65,6 +65,9 @@ export declare const getElementLocale: (element: HTMLElement) => {
  * 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.
  */

package/dist/intl/index.js

@@ -10,8 +10,10 @@ const supportedLocales = (
 const defaultLocale = "en";
 const localeEquivalencies = {
   //#region localeEquivalencies
-  // We use `pt-PT` as it will have the same translations as `pt`, which has no corresponding bundle
-  pt: "pt-PT",
+  // Locale equivalencies aligned with ArcGIS Maps SDK for JavaScript:
+  // https://developers.arcgis.com/javascript/latest/localization/#locale-support
+  // We resolve to `pt-BR` as it will have the same translations as `pt`, which has no corresponding bundle
+  pt: "pt-BR",
   // We support both 'nb' and 'no' (BCP 47) for Norwegian but only `no` has corresponding bundle
   nb: "no",
   // We support both 'nn' and 'no' (BCP 47) for Norwegian but only `no` has corresponding bundle

package/dist/promise/index.cjs

@@ -11,6 +11,20 @@ class Deferred {
     });
   }
 }
+async function forEachWithConcurrency(items, concurrency, callback) {
+  if (items.length === 0) {
+    return;
+  }
+  let index = 0;
+  async function consumeItems() {
+    while (index < items.length) {
+      const item = items[index];
+      index += 1;
+      await callback(item);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, async () => await consumeItems()));
+}
 const devToolsAwareTimeout = (callback, timeout) => {
   const interval = timeout > longTimeoutThreshold ? longTimeoutInterval : timeout / shortTimeoutIntervals;
   let elapsed = 0;
@@ -28,3 +42,4 @@ const longTimeoutInterval = 2e3;
 const shortTimeoutIntervals = 4;
 exports.Deferred = Deferred;
 exports.devToolsAwareTimeout = devToolsAwareTimeout;
+exports.forEachWithConcurrency = forEachWithConcurrency;

package/dist/promise/index.d.cts

@@ -37,6 +37,20 @@ export interface Deferred<T> {
      */
     reject(_error: unknown): void;
 }
+/**
+ * Execute async callbacks against a list with a fixed number of in-flight
+ * operations.
+ * Useful for rate-limiting or to avoid overwhelming resources with too many concurrent operations.
+ *
+ * @example
+ * ```ts
+ * const items = [...lotsOfItems];
+ * await forEachWithConcurrency(items, 5, async (item) => {
+ *   await doSomethingAsync(item);
+ * });
+ * ```
+ */
+export declare function forEachWithConcurrency<T>(items: readonly T[], concurrency: number, callback: (item: T) => Promise<void>): Promise<void>;
 /**
  * Like setTimeout(), but does not advance the clock if the program is
  * stopped on a debugger breakpoint.

package/dist/promise/index.d.ts

@@ -37,6 +37,20 @@ export interface Deferred<T> {
      */
     reject(_error: unknown): void;
 }
+/**
+ * Execute async callbacks against a list with a fixed number of in-flight
+ * operations.
+ * Useful for rate-limiting or to avoid overwhelming resources with too many concurrent operations.
+ *
+ * @example
+ * ```ts
+ * const items = [...lotsOfItems];
+ * await forEachWithConcurrency(items, 5, async (item) => {
+ *   await doSomethingAsync(item);
+ * });
+ * ```
+ */
+export declare function forEachWithConcurrency<T>(items: readonly T[], concurrency: number, callback: (item: T) => Promise<void>): Promise<void>;
 /**
  * Like setTimeout(), but does not advance the clock if the program is
  * stopped on a debugger breakpoint.

package/dist/promise/index.js

@@ -9,6 +9,20 @@ class Deferred {
     });
   }
 }
+async function forEachWithConcurrency(items, concurrency, callback) {
+  if (items.length === 0) {
+    return;
+  }
+  let index = 0;
+  async function consumeItems() {
+    while (index < items.length) {
+      const item = items[index];
+      index += 1;
+      await callback(item);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, async () => await consumeItems()));
+}
 const devToolsAwareTimeout = (callback, timeout) => {
   const interval = timeout > longTimeoutThreshold ? longTimeoutInterval : timeout / shortTimeoutIntervals;
   let elapsed = 0;
@@ -26,5 +40,6 @@ const longTimeoutInterval = 2e3;
 const shortTimeoutIntervals = 4;
 export {
   Deferred,
-  devToolsAwareTimeout
+  devToolsAwareTimeout,
+  forEachWithConcurrency
 };

package/dist/string/index.d.cts

@@ -62,15 +62,18 @@ export declare const addLtrMark: (value: string | undefined) => string;
 export type UUID = ReturnType<typeof crypto.randomUUID>;
 /**
  * Generate a GUID string.
+ *
+ * If your component is using shadow root, the DOM element IDs do not need
+ * to be globally unique - IDs are scoped to the shadow root.
+ *
+ * Avoid using GUID and other non-deterministic output in render() as they
+ * cause SSR hydration issues and snapshot test instability.
+ *
  * @example
  * ```ts
  * const id = generateGuid();
  * // 00000000-0000-0000-0000-000000000000.
  * ```
- *
- * @remarks
- * If your component is using shadow root, the DOM element IDs do not need
- * to be globally unique.
  */
 export declare const generateGuid: () => UUID;
 /**
@@ -89,7 +92,7 @@ export declare const getMinorVersion: (version: string) => string;
  * 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
+ * @see https://webgis.esri.com/sdk/contributing/licensing
  * @example
  * ```ts
  * const preamble = getPreamble("5.0.1-next.456");

package/dist/string/index.d.ts

@@ -62,15 +62,18 @@ export declare const addLtrMark: (value: string | undefined) => string;
 export type UUID = ReturnType<typeof crypto.randomUUID>;
 /**
  * Generate a GUID string.
+ *
+ * If your component is using shadow root, the DOM element IDs do not need
+ * to be globally unique - IDs are scoped to the shadow root.
+ *
+ * Avoid using GUID and other non-deterministic output in render() as they
+ * cause SSR hydration issues and snapshot test instability.
+ *
  * @example
  * ```ts
  * const id = generateGuid();
  * // 00000000-0000-0000-0000-000000000000.
  * ```
- *
- * @remarks
- * If your component is using shadow root, the DOM element IDs do not need
- * to be globally unique.
  */
 export declare const generateGuid: () => UUID;
 /**
@@ -89,7 +92,7 @@ export declare const getMinorVersion: (version: string) => string;
  * 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
+ * @see https://webgis.esri.com/sdk/contributing/licensing
  * @example
  * ```ts
  * const preamble = getPreamble("5.0.1-next.456");

package/dist/type/index.d.cts

@@ -4,7 +4,7 @@
  */
 export type nil = null | undefined;
 /**
- * @deprecated Import from `__esri.IHandle` instead
+ * @deprecated import type { ResourceHandle } from "@arcgis/core/core/Handles.js";
  */
 export type IHandle = {
     remove: () => void;
@@ -18,7 +18,7 @@ export type Nil = nil;
  * 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
+ * https://webgis.esri.com/sdk/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.

package/dist/type/index.d.ts

@@ -4,7 +4,7 @@
  */
 export type nil = null | undefined;
 /**
- * @deprecated Import from `__esri.IHandle` instead
+ * @deprecated import type { ResourceHandle } from "@arcgis/core/core/Handles.js";
  */
 export type IHandle = {
     remove: () => void;
@@ -18,7 +18,7 @@ export type Nil = nil;
  * 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
+ * https://webgis.esri.com/sdk/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.

package/package.json

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