@arcgis/toolkit 5.1.0-next.7 → 5.1.0-next.70

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

@@ -19,15 +19,15 @@ type LogOptions = {
 type EsriConfig = {
     log: {
         /**
-         * @link {https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#LogInterceptor}
+         * @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/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}.
+ * 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/api-reference/esri-config.html}
+ * @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

package/dist/log/index.d.ts

@@ -19,15 +19,15 @@ type LogOptions = {
 type EsriConfig = {
     log: {
         /**
-         * @link {https://developers.arcgis.com/javascript/latest/api-reference/esri-config.html#LogInterceptor}
+         * @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/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}.
+ * 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/api-reference/esri-config.html}
+ * @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

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/webgis/contributing/licensing
  * @example
  * ```ts
  * const preamble = getPreamble("5.0.1-next.456");
@@ -101,6 +104,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

@@ -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/webgis/contributing/licensing
  * @example
  * ```ts
  * const preamble = getPreamble("5.0.1-next.456");
@@ -101,6 +104,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/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;

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;

package/package.json

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