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

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);

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

@@ -5,10 +5,48 @@ import type { UtilityNetworkTraceResultItemState } from "../arcgis-utility-netwo
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
 /**
- * Trace result item for displaying [function](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#globalFunctionResults) results from a trace.
+ * The Utility Network Trace Functions Result Item component displays the
+ * [function results](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/TraceResult/#globalFunctionResults)
+ * returned by a utility network trace. It displays function results in a table with the function
+ * [name](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/FunctionResult/#functionName)
+ * and [value](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/FunctionResult/#result).
+ * If a function name is unavailable, the component displays the function result's
+ * [network attribute name](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/FunctionResult/#networkAttributeName)
+ * and [function type](https://developers.arcgis.com/javascript/latest/references/core/rest/networks/support/FunctionResult/#functionType).
+ * Function results without a network attribute name, function type, or result value are not displayed.
+ *
+ * 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
+ * [trace result](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/#traceResult) property.
+ *
+ * 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.
  *
  * @since 5.2
+ * @example
+ * The following example displays function 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 function 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-functions-result-item
+ *         heading="Function summary"
+ *       ></arcgis-utility-network-trace-functions-result-item>
+ *     </arcgis-utility-network-trace-results>
+ *   </arcgis-utility-network-trace-analysis>
+ * </arcgis-map>
+ * ```
  * @see [Set up functions](https://doc.esri.com/en/arcgis-pro/latest/help/data/utility-network/configure-a-trace.html#CBB)
+ * @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-elements-result-item](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-elements-result-item/)
  */
 export abstract class ArcgisUtilityNetworkTraceFunctionsResultItem extends LitElement {
   /** @internal */
@@ -47,7 +85,10 @@ export abstract class ArcgisUtilityNetworkTraceFunctionsResultItem extends LitEl
    * @default false
    */
   get emitsArcgisResultReady(): true;
-  /** The heading displayed above the result item. */
+  /**
+   * The heading displayed above the function results table.
+   * If not specified or empty, the component uses its localized default heading.
+   */
   accessor heading: string | undefined;
   /**
    * Replace localized message strings with your own strings.
@@ -60,24 +101,30 @@ export abstract class ArcgisUtilityNetworkTraceFunctionsResultItem extends LitEl
       labels?: { functionResults?: string | undefined; } | undefined;
   };
   /**
+   * The processing state of the functions result item.
+   * This property is always `"ready"` because function results require no processing.
+   *
    * @default "ready"
-   * @internal
    */
   get state(): UtilityNetworkTraceResultItemState;
-  /** The trace result containing the function results to render. */
+  /**
+   * The trace result containing the function results to display.
+   * The parent [arcgis-utility-network-trace-results](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-results/) component supplies this property.
+   */
   get traceResult(): TraceResult | undefined;
   /**
-   * Clears the result item.
-   * This result item has no side effects to clear.
-   *
-   * @internal
+   * This method has no effect because the component creates no side effects while processing function results.
+   * Does not emit [@arcgisResultReady](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-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: "state"; }>;
-  /** Fires when the component is finished rendering its results. */
+  /**
+   * Fires when the component finishes processing the current trace result, including when the result contains no function results.
+   * Calling [clearResult()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-utility-network-trace-functions-result-item/#clearResult) does not emit this event.
+   */
   readonly arcgisResultReady: import("@arcgis/lumina").TargetedEvent<this, void>;
   readonly "@eventTypes": {
     arcgisPropertyChange: ArcgisUtilityNetworkTraceFunctionsResultItem["arcgisPropertyChange"]["detail"];