@arcgis/map-components 5.2.0-next.160 → 5.2.0-next.161

package/dist/components/arcgis-floor-filter/interfaces.d.ts

@@ -0,0 +1,72 @@
+import type Geometry from "@arcgis/core/geometry/Geometry.js";
+import type FloorFilterViewModel from "@arcgis/core/widgets/FloorFilter/FloorFilterViewModel.js";
+import type WebMap from "@arcgis/core/WebMap.js";
+import type WebScene from "@arcgis/core/WebScene.js";
+
+export interface IFloorFilterViewModel extends FloorFilterViewModel {
+  filterFacilities: (facilities: Facility[]) => Facility[];
+  filterFeatures: FilterFeatures;
+  filterMenuOpen: boolean;
+  filterMenuType: FilterMenuType;
+  filterMode: FilterMode;
+  filterSites: (sites: Site[]) => Site[];
+  getBaseLevel?: (facility: Facility | null | undefined) => Level | null;
+  getFacility?: (facilityId: null | undefined | string) => Facility | null;
+  getFacilityLevels: (facilityId: null | undefined | string) => Level[];
+  getLevel?: (levelId: null | undefined | string) => Level | null;
+  getSite: (siteId: null | undefined | string) => null | undefined | Site;
+  goTo: (feature: Facility | null | undefined | Site) => void;
+  hasMultipleSites: boolean;
+  isNormalMode: boolean;
+  levelsExpanded: boolean;
+  searchTerm: null | undefined | string;
+  setFloors: (level: Level | null | undefined) => void;
+  state: FloorFilterState;
+  updateWebDocument: (document: WebMap | WebScene) => void;
+}
+
+export type FilterMenuType = "facility" | "site";
+
+export type FilterMode = "base-floors" | "single-floor";
+
+export type FloorFilterState = "disabled" | "loading" | "ready";
+
+export interface FilterFeatures {
+  sites: Sites;
+  facilities: Facilities;
+  levels: Levels;
+}
+
+export interface Sites {
+  sitesInfo: Site[];
+}
+
+export interface Facilities {
+  facilitiesInfo: Facility[];
+}
+
+export interface Levels {
+  levelsInfo: Level[];
+}
+
+export interface Site {
+  id: string;
+  name: string;
+  geometry: Geometry;
+}
+
+export interface Facility {
+  id: string;
+  siteId: null | undefined | string;
+  name: string;
+  geometry: Geometry;
+}
+
+export interface Level {
+  id: string;
+  facilityId: string;
+  longName: null | undefined | string;
+  shortName: null | undefined | string;
+  levelNumber: null | undefined | number;
+  verticalOrder: null | undefined | number;
+}

package/dist/components/arcgis-search/customElement.d.ts

@@ -358,7 +358,6 @@ export abstract class ArcgisSearch extends LitElement {
    * **Note:** Feature layers created from client-side graphics are not supported.
    *
    * @example
-   * // Default sources[] when sources is not specified
    * const search = document.querySelector("arcgis-search");
    * await search.componentOnReady();
    * // set the search sources once the component is ready
@@ -369,7 +368,7 @@ export abstract class ArcgisSearch extends LitElement {
    *     apiKey: "YOUR_ACCESS_TOKEN",
    *     outFields: ["Addr_type"],
    *     name: "ArcGIS World Geocoding Service",
-   *     placeholder: "Adresse",
+   *     placeholder: "Address",
    *     resultSymbol: {
    *        type: "picture-marker",  // autocasts as new PictureMarkerSymbol()
    *        url: this.basePath + "/images/search/search-symbol-32.png",

package/dist/components/arcgis-selection-list/customElement.js

@@ -235,7 +235,7 @@ class k extends x {
         this.itemWithOpenMenu = e;
       }}>${o("action", a`<calcite-action icon=ellipsis .scale=${this.visualScale} slot=trigger .text=${t.menu ?? ""}></calcite-action>`)}${// Only render menu-items for open menu(s) to reduce
       // the total number of list item elements in the DOM at any time.
-      s ? o("dropdown-group", a`<calcite-dropdown-group selection-mode=none>${this.hideZoomToButton ? void 0 : o("zoom-to", a`<calcite-dropdown-item icon-start=layer-zoom-to @calciteDropdownItemSelect=${() => this.goToItem(e)}>${t.zoomTo}</calcite-dropdown-item>`)}${o("select-single", a`<calcite-dropdown-item icon-start=selection-filter @calciteDropdownItemSelect=${() => this.selectItem(e)}>${i ? t.onlySelectFeature : t.onlySelectThis}</calcite-dropdown-item>`)}${o("clear-selection", a`<calcite-dropdown-item icon-start=selection-x @calciteDropdownItemSelect=${() => this.deselectItem(e)}>${l}</calcite-dropdown-item>`)}${this.listItemActionConfigurations?.map((d) => {
+      s ? o("dropdown-group", a`<calcite-dropdown-group selection-mode=none>${!this.hideZoomToButton && !e.isTable ? o("zoom-to", a`<calcite-dropdown-item icon-start=layer-zoom-to @calciteDropdownItemSelect=${() => this.goToItem(e)}>${t.zoomTo}</calcite-dropdown-item>`) : void 0}${o("select-single", a`<calcite-dropdown-item icon-start=selection-filter @calciteDropdownItemSelect=${() => this.selectItem(e)}>${i ? t.onlySelectFeature : t.onlySelectThis}</calcite-dropdown-item>`)}${o("clear-selection", a`<calcite-dropdown-item icon-start=selection-x @calciteDropdownItemSelect=${() => this.deselectItem(e)}>${l}</calcite-dropdown-item>`)}${this.listItemActionConfigurations?.map((d) => {
         const { disabled: n, label: m } = d;
         if (this._isDropdownItemVisible(e, d))
           return o(`custom-action-${m}`, a`<calcite-dropdown-item .disabled=${typeof n == "function" ? n({ item: e }) : !!n} .iconStart=${d.icon ?? void 0} @calciteDropdownItemSelect=${() => d.callback({ item: e })}>${m}</calcite-dropdown-item>`);

package/dist/components/arcgis-utility-network-trace-aggregated-geometry-result-item/customElement.d.ts

@@ -9,9 +9,62 @@ import type { UtilityNetworkTraceResultItemState } from "../arcgis-utility-netwo
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
 /**
- * Trace result item for displaying [aggregated geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#aggregatedGeometry) results from a trace.
+ * The Utility Network Trace Aggregated Geometry Result Item component displays the
+ * [aggregated geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#aggregatedGeometry)
+ * returned by a utility network trace. It creates graphics for the result's line, multipoint, and polygon geometries
+ * and displays them in the view. Provides options to show or hide the graphics, change their color and size.
+ *
+ * Add this component directly to the default slot of [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/).
+ * The parent supplies the required read-only properties for the
+ * [trace result](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#traceResult) and
+ * [MapView](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#view).
+ *
+ * By default, the [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/) component displays the
+ * [aggregated geometry](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/),
+ * [elements](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/), and
+ * [functions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/) result items for the result types
+ * returned by the trace. Adding content to its default slot replaces all default result items. Add each result item
+ * that the custom configuration should display.
+ *
+ * By default, the component creates and manages a graphics layer. Set
+ * [graphicsLayer](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#graphicsLayer) to render the
+ * aggregated geometry graphics in an existing layer instead.
  *
  * @since 5.2
+ * @example
+ * The following example displays aggregated geometry in a custom set of trace result items.
+ * Providing result items in the default slot replaces the parent's default result items.
+ * This example displays only aggregated geometry results.
+ * ```html
+ * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+ *   <arcgis-utility-network-trace-analysis slot="bottom-left">
+ *     <arcgis-utility-network-trace-results slot="results">
+ *       <arcgis-utility-network-trace-aggregated-geometry-result-item>
+ *       </arcgis-utility-network-trace-aggregated-geometry-result-item>
+ *     </arcgis-utility-network-trace-results>
+ *   </arcgis-utility-network-trace-analysis>
+ * </arcgis-map>
+ * ```
+ * @example
+ * Customize the color and size of the aggregated geometry graphics. Setting `hide-graphics` initially hides the
+ * graphics from the map. Users can show them with the component's toggle.
+ * ```html
+ * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+ *   <arcgis-utility-network-trace-analysis slot="bottom-left">
+ *     <arcgis-utility-network-trace-results slot="results">
+ *       <arcgis-utility-network-trace-aggregated-geometry-result-item
+ *         graphics-color="rgba(0, 122, 194, 0.6)"
+ *         selection-size="8"
+ *         hide-graphics
+ *       ></arcgis-utility-network-trace-aggregated-geometry-result-item>
+ *     </arcgis-utility-network-trace-results>
+ *   </arcgis-utility-network-trace-analysis>
+ * </arcgis-map>
+ * ```
+ * @see [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/)
+ * @see [arcgis-utility-network-trace-analysis](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/)
+ * @see [arcgis-utility-network-trace-elements-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/)
+ * @see [arcgis-utility-network-trace-functions-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/)
  * @see [Result types](https://doc.esri.com/en/arcgis-pro/latest/help/data/utility-network/configure-a-trace.html#DA5)
  */
 export abstract class ArcgisUtilityNetworkTraceAggregatedGeometryResultItem extends LitElement {
@@ -57,23 +110,39 @@ export abstract class ArcgisUtilityNetworkTraceAggregatedGeometryResultItem exte
    * @default false
    */
   get emitsArcgisResultReady(): true;
-  /** The graphics which represent the aggregated geometry results from the trace. */
+  /**
+   * The graphics created from the line, multipoint, and polygon geometries in the aggregated geometry result.
+   *
+   * Read this property after
+   * [@arcgisResultReady](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#event-arcgisResultReady) fires.
+   */
   get geometryGraphics(): Graphic[];
   /**
-   * The color used for the aggregated geometry graphics.
-   * Default value is #FFFF00.
+   * The color of the aggregated geometry graphics.
+   * The default is yellow with 0.6 opacity.
+   *
+   * @see [Color constructor](https://developers.arcgis.com/javascript/latest/references/core/Color/#constructors-summary)
    */
   accessor graphicsColor: Color;
   /**
-   * The layer used to render the graphics which represent the aggregated geometry result.
-   * If this property is not specified, a new layer will be created on the map.
+   * The layer used to render the aggregated geometry graphics.
+   *
+   * When the result is cleared or the component is destroyed:
+   *
+   * - If the layer is provided by the application, the component removes only the aggregated geometry graphics it
+   *   created. The layer and any other graphics remain unchanged.
+   * - If no layer is provided, the component creates and manages a layer. It removes the aggregated geometry graphics
+   *   and the component-owned layer from the map.
    */
   accessor graphicsLayer: GraphicsLayer | undefined;
-  /** The heading of the result item. */
+  /** The heading displayed above the aggregated geometry controls. */
   accessor heading: string | undefined;
   /**
-   * Whether to hide the aggregated geometry [graphics](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#geometryGraphics)
-   * from the map when the trace result contains aggregated geometry results.
+   * Whether to hide the aggregated geometry graphics from the map.
+   *
+   * When true, the graphics remain available through
+   * [geometryGraphics](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#geometryGraphics) but are removed
+   * from the [graphicsLayer](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#graphicsLayer).
    *
    * @default false
    */
@@ -92,28 +161,36 @@ export abstract class ArcgisUtilityNetworkTraceAggregatedGeometryResultItem exte
       showGraphics?: string | undefined;
   };
   /**
-   * The size of the aggregated geometry graphics to render, in points.
+   * The marker size and line or polygon-outline width of the aggregated geometry graphics, in points.
+   * The default is 12.
    *
    * @default 12
    */
   accessor selectionSize: number;
   /**
-   * Whether the component has finished adding aggregated geometry graphics to the map.
+   * The processing state of the aggregated geometry result item: `"loading"` while processing a trace result and
+   * `"ready"` when no processing is in progress.
    *
    * @default "ready"
    */
   get state(): UtilityNetworkTraceResultItemState;
-  /** The trace result containing the aggregated geometry result to render graphics for. */
+  /** The trace result containing the aggregated geometry to display. */
   get traceResult(): TraceResult | undefined;
   /**
-   * The view associated with the component.
-   * > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-utility-network-trace-aggregated-geometry-result-item component will be associated with a map or scene component rather than using the `view` property.
+   * The MapView supplied by the parent [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/) component.
+   * Used to display the aggregated geometry graphics.
    */
   get view(): MapView | undefined;
   /**
    * Removes the aggregated geometry graphics from the
    * [graphicsLayer](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#graphicsLayer).
-   * If the layer was created by the component, it is also removed from the map.
+   * If the layer was created by the component, it is also removed from the map. The method clears
+   * [geometryGraphics](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#geometryGraphics) and resets
+   * [state](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#state) to `"ready"`.
+   *
+   * This method does not clear the parent-provided
+   * [traceResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#traceResult) or emit
+   * [@arcgisResultReady](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#event-arcgisResultReady).
    */
   clearResult(): void;
   /** Permanently destroy the component. */
@@ -121,13 +198,16 @@ export abstract class ArcgisUtilityNetworkTraceAggregatedGeometryResultItem exte
   /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
   readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "hideGraphics" | "geometryGraphics" | "graphicsColor" | "selectionSize" | "state"; }>;
   /**
-   * Fires when the component finishes processing the aggregated geometry results.
+   * Fires when the component finishes processing the current trace result.
    *
-   * If the component has a valid trace result with aggregated geometry results, this fires
-   * when the aggregated geometry graphics have been added to the map.
+   * For a result with aggregated geometry, the event fires after the graphics are created and, unless
+   * [hideGraphics](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#hideGraphics) is `true`, added to
+   * the map. The event also fires when processing completes without graphics because the result, aggregated geometry,
+   * or map view is unavailable.
    *
-   * If the component does not have a valid map or trace result, this fires when the
-   * component has finished loading.
+   * Clearing a result with
+   * [clearResult()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/#clearResult) does not emit this
+   * event.
    */
   readonly arcgisResultReady: import("@arcgis/lumina").TargetedEvent<this, void>;
   readonly "@eventTypes": {

package/dist/components/arcgis-utility-network-trace-analysis/customElement.d.ts

@@ -93,7 +93,6 @@ import type { UtilityNetworkTraceAnalysisState } from "@arcgis/core/networks/Uti
  * @slot
  * [results] - Slot for instances of [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/),
  * for displaying the results of one or more traces.
- * @internal
  * @since 5.0
  */
 export abstract class ArcgisUtilityNetworkTraceAnalysis extends LitElement {

package/dist/components/arcgis-utility-network-trace-elements-result-item/customElement.d.ts

@@ -12,10 +12,69 @@ import type { UtilityNetworkTraceResultItemState } from "../arcgis-utility-netwo
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
 /**
- * Trace result item for displaying [element](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements) results from a trace.
+ * The Utility Network Trace Elements Result Item component displays features corresponding to the
+ * [elements](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements)
+ * returned by a utility network trace. It queries utility network layers for features, highlights trace elements
+ * in the view, and uses [arcgis-features-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/) to display the queried features in a list.
+ *
+ * For traces containing only element results, the features list opens automatically. For traces containing multiple
+ * result types, users open the features list by selecting the elements result item in the trace results component.
+ * See [isFeaturesListShown](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#isFeaturesListShown) for details.
+ *
+ * Add this component directly to the default slot of [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/).
+ * The parent supplies the required read-only properties for the
+ * [trace result](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#traceResult),
+ * [utility network](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#utilityNetwork), and
+ * [MapView](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#view).
+ * Configure other settings, such as [layers](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#layers),
+ * [disableHighlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#disableHighlight), and
+ * [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#hideFeatureResults), on this component.
+ *
+ * By default, the [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/) component displays the
+ * [aggregated geometry](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/),
+ * [elements](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/), and
+ * [functions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/) result items for the result types
+ * returned by the trace. Adding content to its default slot replaces all default result items. Add each result item
+ * that the custom configuration should display.
+ *
+ * Use [layers](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#layers) to restrict feature queries to
+ * specific utility network layers.
  *
  * @since 5.2
+ * @example
+ * The following example displays element results in a custom set of trace result items.
+ * Providing result items in the default slot replaces the parent's default result items.
+ * This example displays only element results.
+ * ```html
+ * <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
+ *   <arcgis-utility-network-trace-analysis slot="bottom-left">
+ *     <arcgis-utility-network-trace-results slot="results">
+ *       <arcgis-utility-network-trace-elements-result-item></arcgis-utility-network-trace-elements-result-item>
+ *     </arcgis-utility-network-trace-results>
+ *   </arcgis-utility-network-trace-analysis>
+ * </arcgis-map>
+ * ```
+ * @example
+ * Using the markup above, register these listeners before running a trace to access the queried features
+ * when the elements result item is ready and respond when the selected result feature changes.
+ * ```js
+ * const resultItem = document.querySelector("arcgis-utility-network-trace-elements-result-item");
+ *
+ * resultItem.addEventListener("arcgisResultReady", () => {
+ *   console.log("Trace result features:", resultItem.features);
+ * });
+ *
+ * resultItem.addEventListener("arcgisPropertyChange", (event) => {
+ *   if (event.detail.name === "selectedResultFeature") {
+ *     console.log("Selected feature:", resultItem.selectedResultFeature);
+ *   }
+ * });
+ * ```
  * @see [Result types](https://doc.esri.com/en/arcgis-pro/latest/help/data/utility-network/configure-a-trace.html#DA5)
+ * @see [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/)
+ * @see [arcgis-utility-network-trace-analysis](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-analysis/)
+ * @see [arcgis-utility-network-trace-aggregated-geometry-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-aggregated-geometry-result-item/)
+ * @see [arcgis-utility-network-trace-functions-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/)
  */
 export abstract class ArcgisUtilityNetworkTraceElementsResultItem extends LitElement {
   /** @internal */
@@ -71,28 +130,36 @@ export abstract class ArcgisUtilityNetworkTraceElementsResultItem extends LitEle
    * @default false
    */
   get emitsArcgisResultReady(): true;
-  /** The features corresponding to the trace result elements. */
+  /**
+   * The features successfully queried for the current trace result elements.
+   * Elements without a matching query layer are not included.
+   */
   get features(): Graphic[];
-  /** The heading of the result item. */
+  /**
+   * The label of the elements result item that opens the features list.
+   * If not specified or empty, the component uses its localized default label.
+   */
   accessor heading: string | undefined;
   /**
-   * Indicates whether to hide the action bar that holds the feature's
-   * [actions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features/#actions)
-   * when selecting trace locations and viewing trace result features.
+   * Whether to hide the action bar when viewing trace result features.
+   * The action bar contains the feature's [actions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/#actions).
    *
    * @default false
    */
   accessor hideActionBar: boolean;
   /**
-   * Whether to hide feature results.
-   * If true, the component renders a placeholder string instead of a button to view features.
+   * Whether to hide the elements result item and the features list.
+   * If true, the component renders a placeholder string instead of the elements result item.
    * When true, features are still queried and are available through [features](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#features).
    *
+   * This property does not disable highlighting. Use
+   * [disableHighlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#disableHighlight) to hide trace-element highlights.
+   *
    * @default false
    */
   accessor hideFeatureResults: boolean;
   /**
-   * Whether to hide the placeholder string when feature results are hidden.
+   * Whether to hide the placeholder string when the elements result item and the features list are hidden.
    *
    * When this property and [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#hideFeatureResults) are both set to `true`,
    * nothing is rendered for trace result elements. However, features are still queried and are available through
@@ -102,30 +169,34 @@ export abstract class ArcgisUtilityNetworkTraceElementsResultItem extends LitEle
    */
   accessor hidePlaceholder: boolean;
   /**
-   * Indicates whether default actions are disabled (hidden) when viewing trace result features.
-   * This property must be set to `true` to disable default actions.
+   * Whether to hide the default actions when viewing trace result features.
    *
    * @default false
    */
   accessor includeDefaultActionsDisabled: boolean;
   /**
-   * Whether the list of feature results is being viewed.
-   * When true, the component renders the trace result features as a list in the [arcgis-features-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/) component.
+   * Whether the features list is currently displayed.
+   * Returns `true` when the component is displaying the features list using the [arcgis-features-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/) component.
    *
-   * This property is always false when [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#hideFeatureResults) is true.
+   * Always returns `false` when [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#hideFeatureResults) is set to `true`.
    *
-   * If [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#hideFeatureResults) is not set, the list opens automatically when
+   * If [hideFeatureResults](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#hideFeatureResults) is not set, the features list opens automatically when
    * a trace result containing only [elements](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#elements) loads,
-   * or when the user chooses to view Feature results. Closing the list sets this property to false.
+   * or when the user selects the [elements result item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/). Closing the features list causes this property to return `false`.
    *
    * @default false
    */
   get isFeaturesListShown(): boolean;
   /**
-   * The utility network layers used to query trace result features.
+   * The utility network layers and tables used to query trace result features.
+   *
+   * When the array is empty, the component uses the map's layers and tables that belong to
+   * the selected [utilityNetwork](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#utilityNetwork).
+   * Entries that do not belong to that utility network are ignored.
    *
-   * If none are provided, the component uses all layers in the map belonging to
-   * the specified [utilityNetwork](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#utilityNetwork).
+   * Set this property before the trace result is processed. Changing it does not requery the current result.
+   *
+   * This property restricts which layers are queried for features. It does not restrict highlighting of trace result features.
    */
   accessor layers: Layer[];
   /**
@@ -139,14 +210,19 @@ export abstract class ArcgisUtilityNetworkTraceElementsResultItem extends LitEle
       resultFeaturesAreHidden?: string | undefined;
   };
   /**
-   * The number of unique network element results,
-   * including elements that did not match any layer in the map.
+   * The number of successfully queried features plus unique trace elements without a matching query layer.
+   *
+   * This value can be lower than the number of elements returned by the trace. For example:
+   * - Trace result elements that only differ by a terminal ID are treated as one feature.
+   * - Feature queries may fail or return no matching features.
    */
   get numResults(): number;
   /**
-   * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
+   * The reference element, or its ID, forwarded to the embedded
+   * [Features component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-features-next/#referenceElement).
    *
-   * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
+   * Setting this property does not remove the requirement to use this component as a child of
+   * [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/).
    */
   accessor referenceElement: ArcgisReferenceElement | string | undefined;
   /**
@@ -158,7 +234,8 @@ export abstract class ArcgisUtilityNetworkTraceElementsResultItem extends LitEle
    */
   get selectedResultFeature(): Graphic | undefined;
   /**
-   * Whether the component has finished querying trace result features.
+   * The processing state of the elements result item: `"loading"` while processing a trace result and `"ready"` when no
+   * processing is in progress. A `"ready"` state does not necessarily mean that every feature query succeeded.
    *
    * @default "ready"
    */
@@ -168,20 +245,31 @@ export abstract class ArcgisUtilityNetworkTraceElementsResultItem extends LitEle
   /** The utility network used to query the trace result features. */
   get utilityNetwork(): UtilityNetwork | undefined;
   /**
-   * The view associated with the component.
-   * > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-utility-network-trace-elements-result-item component will be associated with a map or scene component rather than using the `view` property.
+   * The MapView supplied by the parent [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/) component.
+   * Used to query utility network layers and highlight trace elements.
    */
   get view(): MapView | undefined;
   /**
-   * Cancels any feature queries in progress, removes feature highlights from the map,
-   * and clears [features](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#features).
+   * Cancels feature queries in progress, removes trace-element highlights from the map,
+   * clears [features](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#features), closes the features list,
+   * and resets [state](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#state) to `"ready"`.
+   *
+   * Does not clear the parent-provided [traceResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#traceResult)
+   * or emit [@arcgisResultReady](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#event-arcgisResultReady).
    */
   clearResult(): void;
   /** Permanently destroy the component. */
   destroy(): Promise<void>;
   /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
   readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "features" | "isFeaturesListShown" | "selectedResultFeature" | "state"; }>;
-  /** Fires when the component finishes querying all features for the trace result elements. */
+  /**
+   * Fires when processing the current trace result finishes, including when a query fails.
+   * The [features](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#features) property contains the features
+   * successfully queried.
+   *
+   * Clearing an in-progress result with
+   * [clearResult()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/#clearResult) does not emit this event.
+   */
   readonly arcgisResultReady: import("@arcgis/lumina").TargetedEvent<this, void>;
   /** Emitted when an action is triggered on the component. */
   readonly arcgisTriggerAction: import("@arcgis/lumina").TargetedEvent<this, ActionEvent>;

package/dist/components/arcgis-utility-network-trace-elements-result-item/customElement.js

@@ -2,10 +2,10 @@
 import { c as F } from "../../chunks/runtime.js";
 import { ref as E } from "lit/directives/ref.js";
 import { getOrCreateMapValue as v } from "@arcgis/core/applications/Components/featureUtils.js";
-import { LitElement as L, createEvent as f } from "@arcgis/lumina";
+import { LitElement as L, createEvent as y } from "@arcgis/lumina";
 import { usePropertyChange as T, bypassReadOnly as o } from "@arcgis/lumina/controllers";
 import { log as d, composeMissingPropertyMessage as m } from "@arcgis/toolkit/log";
-import { css as k, html as y } from "lit";
+import { css as k, html as f } from "lit";
 import { u as I } from "../../chunks/useT9n.js";
 import { i as g, l as p, t as c, c as A } from "../../chunks/async-utils.js";
 import { c as S, q as P, d as w, e as $ } from "../../chunks/layer-utils.js";
@@ -13,7 +13,7 @@ import { i as R } from "../../chunks/utils5.js";
 const C = k`arcgis-features-next{height:100%}.elements-list-item{border:solid 1px var(--calcite-color-border-3);border-radius:var(--calcite-corner-radius-sm)}.features-hidden{color:var(--calcite-color-text-3);font-size:var(--calcite-font-size);overflow-wrap:anywhere}`;
 class D extends L {
   constructor() {
-    super(...arguments), this._messages = I({ blocking: !0 }), this.#n = !0, this.#i = [], this.#t = [], this.#r = /* @__PURE__ */ new Map(), this.#a = /* @__PURE__ */ new Map(), this.#h = !1, this.#l = /* @__PURE__ */ new Map(), this.#o = /* @__PURE__ */ new Map(), this.#e = [], this._isFeaturesSelected = !1, this.autoDestroyDisabled = !1, this.disableHighlight = !1, this.emitsArcgisResultReady = !0, this.features = [], this.hideActionBar = !1, this.hideFeatureResults = !1, this.hidePlaceholder = !1, this.includeDefaultActionsDisabled = !1, this.layers = [], this.state = "ready", this.arcgisPropertyChange = T()("features", "isFeaturesListShown", "selectedResultFeature", "state"), this.arcgisResultReady = f(), this.arcgisTriggerAction = f();
+    super(...arguments), this._messages = I({ blocking: !0 }), this.#n = !0, this.#i = [], this.#t = [], this.#r = /* @__PURE__ */ new Map(), this.#a = /* @__PURE__ */ new Map(), this.#h = !1, this.#l = /* @__PURE__ */ new Map(), this.#o = /* @__PURE__ */ new Map(), this.#e = [], this._isFeaturesSelected = !1, this.autoDestroyDisabled = !1, this.disableHighlight = !1, this.emitsArcgisResultReady = !0, this.features = [], this.hideActionBar = !1, this.hideFeatureResults = !1, this.hidePlaceholder = !1, this.includeDefaultActionsDisabled = !1, this.layers = [], this.state = "ready", this.arcgisPropertyChange = T()("features", "isFeaturesListShown", "selectedResultFeature", "state"), this.arcgisResultReady = y(), this.arcgisTriggerAction = y();
   }
   static {
     this.properties = { _featuresComponentElement: 16, _isFeaturesSelected: 16, actions: 0, autoDestroyDisabled: 5, disableHighlight: 5, emitsArcgisResultReady: 32, features: 32, heading: 1, hideActionBar: 5, hideFeatureResults: 5, hidePlaceholder: 5, includeDefaultActionsDisabled: 5, isFeaturesListShown: 32, layers: 0, messageOverrides: 0, numResults: 32, referenceElement: 1, selectedResultFeature: 32, state: 32, traceResult: 32, utilityNetwork: 32, view: 32 };
@@ -23,7 +23,7 @@ class D extends L {
   }
   #n;
   #i;
-  get #y() {
+  get #f() {
     if (!this.traceResult)
       return !1;
     const { elements: e, globalFunctionResults: t, aggregatedGeometry: s } = this.traceResult;
@@ -67,7 +67,7 @@ class D extends L {
         d("warn", this, "This component must be used as a child of `arcgis-utility-network-trace-results`.");
         return;
       }
-      const t = (s) => this.#f(s);
+      const t = (s) => this.#y(s);
       return e.addEventListener("arcgisPropertyChange", t), o(() => {
         this.traceResult = e.traceResult, this.utilityNetwork = e.utilityNetwork, this.view = e.view;
       }), () => {
@@ -83,7 +83,7 @@ class D extends L {
   loaded() {
     this.traceResult && (this.traceResult.elements || d("error", this, m("traceResult.elements")), this.utilityNetwork || d("error", this, m("utilityNetwork")));
   }
-  #f(e) {
+  #y(e) {
     if (e.target !== this.#c)
       return;
     const { target: t } = e;
@@ -153,7 +153,7 @@ class D extends L {
     }
   }
   async #d() {
-    this.clearResult(), this._isFeaturesSelected = this.#y;
+    this.clearResult(), this._isFeaturesSelected = this.#f;
     const e = () => {
       o(() => this.state = "ready"), this.arcgisResultReady.emit();
     }, t = A(async (s) => {
@@ -215,14 +215,14 @@ class D extends L {
     e.stopPropagation(), this.arcgisTriggerAction.emit(e.detail);
   }
   #k() {
-    return y`<div class="features-hidden">${this._messages.resultFeaturesAreHidden}</div>`;
+    return f`<div class="features-hidden">${this._messages.resultFeaturesAreHidden}</div>`;
   }
   #I() {
     const { heading: e, _messages: t } = this;
-    return y`<calcite-list .label=${t.headings.features}><calcite-list-item class="elements-list-item" .label=${e || t.headings.features} @calciteListItemSelect=${() => this._isFeaturesSelected = !0}><calcite-chip .label=${t.labels.numFeatures} scale=s slot=content-end>${this.numResults}</calcite-chip><calcite-icon icon=chevron-right slot=content-end></calcite-icon></calcite-list-item></calcite-list>`;
+    return f`<calcite-list .label=${t.headings.features}><calcite-list-item class="elements-list-item" .label=${e || t.headings.features} @calciteListItemSelect=${() => this._isFeaturesSelected = !0}><calcite-chip .label=${t.labels.numFeatures} scale=s slot=content-end>${this.numResults}</calcite-chip><calcite-icon flip-rtl icon=chevron-right slot=content-end></calcite-icon></calcite-list-item></calcite-list>`;
   }
   render() {
-    return !this.traceResult?.elements.length || this.manager.destroyed ? null : this.hideFeatureResults ? this.hidePlaceholder ? null : this.#k() : this.isFeaturesListShown ? y`<arcgis-features-next .actions=${this.actions} .autoDestroyDisabled=${this.autoDestroyDisabled} .defaultPopupTemplateEnabled=${this.#n} .features=${this.features} .hideActionBar=${this.hideActionBar} hide-select-feature .includeDefaultActionsDisabled=${this.includeDefaultActionsDisabled} initial-display-mode=list .messageOverrides=${this.messageOverrides} open .referenceElement=${this.referenceElement} .view=${this.view} @arcgisClose=${() => this._isFeaturesSelected = !1} @arcgisPropertyChange=${this.#L} @arcgisTriggerAction=${this.#T} ${E(this.#g)}></arcgis-features-next>` : this.#I();
+    return !this.traceResult?.elements.length || this.manager.destroyed ? null : this.hideFeatureResults ? this.hidePlaceholder ? null : this.#k() : this.isFeaturesListShown ? f`<arcgis-features-next .actions=${this.actions} .autoDestroyDisabled=${this.autoDestroyDisabled} .defaultPopupTemplateEnabled=${this.#n} .features=${this.features} .hideActionBar=${this.hideActionBar} hide-select-feature .includeDefaultActionsDisabled=${this.includeDefaultActionsDisabled} initial-display-mode=list .messageOverrides=${this.messageOverrides} open .referenceElement=${this.referenceElement} .view=${this.view} @arcgisClose=${() => this._isFeaturesSelected = !1} @arcgisPropertyChange=${this.#L} @arcgisTriggerAction=${this.#T} ${E(this.#g)}></arcgis-features-next>` : this.#I();
   }
 }
 F("arcgis-utility-network-trace-elements-result-item", D);