Types
import type { UtilityNetworkTraceAnalysisDisplayMode, UtilityNetworkTraceResultItemState, UtilityNetworkTraceResultItem } from "@arcgis/map-components/components/arcgis-utility-network-trace-analysis/types.js";

Type definitions

UtilityNetworkTraceAnalysisDisplayMode

Type definition
Type
"add-spatial-feature" | "add-spatial-instructions" | "default"

UtilityNetworkTraceResultItemState

Type definition
Type
"disabled" | "loading" | "ready"

UtilityNetworkTraceResultItem

Type definition
Since
ArcGIS Maps SDK for JavaScript 5.2

Describes the properties and lifecycle methods used by the built-in trace result item components.

Use this interface as a reference when creating a custom trace result item component to place in the default slot of arcgis-utility-network-trace-results. It describes the context, configuration, readiness, and cleanup behavior you may want to implement, depending on what your custom result item component displays or does.

A custom result item component only needs the optional context and configuration properties it uses.

The trace results component does not assign these properties to slotted custom result item components. Set the properties your custom result item component needs, for example by reading the trace result from the parent trace results component. Listen for the parent's arcgis-utility-network-trace-results.@arcgisPropertyChange event to handle subsequent changes, ignoring events whose target is not the parent. Remove event listeners when the custom result item component disconnects.

Coordinate result readiness

Set UtilityNetworkTraceResultItem to true before slotting a custom item if the trace results component should wait for that result item to emit arcgisResultReady before displaying trace results. For example, a result item that queries features should set emitsArcgisResultReady to true and emit arcgisResultReady after the feature queries finish and the result item is ready to display its results.

The trace results component stays in its loading state until every participating result item (including default result items) has signaled completion by emitting arcgisResultReady. The trace results component then emits arcgis-utility-network-trace-results.@arcgisResultsReady.

Signal completion even when processing produces no applicable results or fails, after displaying any error. Otherwise, the trace results component keeps waiting.

Set emitsArcgisResultReady to false for an item that does not need to delay readiness, such as static content about the trace results.

Clear output between trace results

Specify a UtilityNetworkTraceResultItem method to clean up a custom result item component's side effects. The trace results component calls this method when its trace result changes or arcgis-utility-network-trace-results.clearResults() is called. For example, if a custom result item adds graphics to the map, its clearResult callback may remove the graphics from the map.

Cleanup is independent of readiness: an item with emitsArcgisResultReady set to false can still provide clearResult. Cleanup must be safe to repeat and must not emit arcgisResultReady or destroy the item. Keep the item ready to process the next trace result.

Adding any content to the trace results component's default slot replaces all default result items, so include each built-in or custom item you want to display.

See also

layers

Property
Type
Layer[] | undefined

The layers and tables used to query features associated with the trace result.

The elements result item uses this configuration to restrict feature queries to specific utility network layers and tables. An empty array uses the map's layers and tables that belong to the selected utility network.

The trace results component forwards its layers only to its internally created elements result item. Custom result items decide how to use this property.

See also

heading

Property
Type
string | undefined

The heading displayed by the result item.

Configure this on the custom result item component, not on the trace results component. The trace results component heading describes the whole trace rather than an individual item.

For example, the functions result item displays this heading above its table and uses a localized default when it is omitted or empty. Custom items control where the heading appears and whether a default is provided.

See also

traceResult

Property
Type
TraceResult | undefined

The trace result processed and displayed by the result item.

Read this value from the parent trace results component. Built-in items process the relevant part of the result: elements, aggregated geometry, or function results. Custom items can process any part they need.

To access the full trace response in JSON format, including fields not exposed by the TraceResult class, use TraceResult.sourceJSON.

Handle an undefined value when no result is available, and replace output from the previous result when a new result arrives.

If the item participates in readiness tracking, signal completion even when the result contains no data relevant to the item.

See also

utilityNetwork

Property
Type
UtilityNetwork | undefined

The utility network associated with the trace result.

Read this value from the parent trace results component. The elements result item uses it to identify utility network layers and resolve trace elements to features.

See also

view

Property
Type
MapView | undefined

The map view used to display and interact with the trace result.

Read this value from the parent trace results component. The elements result item uses it to query layers and highlight features. The aggregated geometry result item uses it to display graphics.

See also

emitsArcgisResultReady

Property
Type
boolean

Indicates whether the result item emits an arcgisResultReady event after processing a trace result.

Set this to true before adding the item to the trace results component to participate in readiness tracking. Dispatch arcgisResultReady from the custom result item component after processing a trace result. No event detail is required. Once all participating result item components (including default result items) emit arcgisResultReady, the trace results component changes its state to "ready" and emits arcgis-utility-network-trace-results.@arcgisResultsReady.

Signal completion when processing finishes, including when there are no applicable results or processing fails. If this property is true and a custom result item never emits arcgisResultReady, the trace results component remains in its "loading" state and does not emit arcgisResultsReady. Do not emit arcgisResultReady for work canceled by clearResult.

Set this to false when the trace results component does not need to wait for the custom result item, e.g., displaying static content for the trace result.

See also
Example

Set the property and dispatch the event after the current result has finished processing:

class MyTraceResultItem extends HTMLElement {
emitsArcgisResultReady = true;
finishProcessing(): void {
this.dispatchEvent(new CustomEvent("arcgisResultReady"));
}
}

clearResult

Property
Type
() => void

Clears the result item's rendered output and side effects, such as graphics added to the map.

The trace results component calls this function when its arcgis-utility-network-trace-results.clearResults() method is called or its trace result changes.

Cancel pending work, clear the item's stored trace result and rendered output, and undo other side effects here. Ensure canceled work cannot restore stale output or emit arcgisResultReady. It must be safe to call this function when the item is already clear.

This function is synchronous and must not emit arcgisResultReady. It does not destroy the item or remove its context listeners; the item can be reused for subsequent trace results.

See also
Example

This excerpt shows cleanup for the query example above. Abort the pending query, remove only the graphics created by this component, and clear any displayed error:

import type Graphic from "@arcgis/core/Graphic.js";
import type MapView from "@arcgis/core/views/MapView.js";
class MyTraceResultItem extends HTMLElement {
#controller?: AbortController;
#view?: MapView;
#graphics: Graphic[] = [];
clearResult(): void {
this.#controller?.abort();
this.#controller = undefined;
this.#view?.graphics.removeMany(this.#graphics);
this.#view = undefined;
this.#graphics = [];
this.replaceChildren();
}
}
Examples

After registering a custom element named my-trace-result-item, add it alongside a built-in result item. The custom item is responsible for reading its context from the trace results component and processing each trace result.

<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>
<my-trace-result-item></my-trace-result-item>
</arcgis-utility-network-trace-results>
</arcgis-utility-network-trace-analysis>
</arcgis-map>

This custom element excerpt queries up to 25 point features in the current view extent, adds them to the map, and removes them when clearResult is called.

import type FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
import type Graphic from "@arcgis/core/Graphic.js";
import type MapView from "@arcgis/core/views/MapView.js";
class MyTraceResultItem extends HTMLElement {
emitsArcgisResultReady = true;
#controller?: AbortController;
#view?: MapView;
#graphics: Graphic[] = [];
async processResult(layer: FeatureLayer, view: MapView): Promise<void> {
this.clearResult();
const controller = new AbortController();
this.#controller = controller;
try {
const query = layer.createQuery();
query.geometry = view.extent;
query.num = 25;
query.returnGeometry = true;
query.outSpatialReference = view.spatialReference;
const { features } = await layer.queryFeatures(query, { signal: controller.signal });
if (controller.signal.aborted) {
return;
}
this.#view = view;
this.#graphics = features;
view.graphics.addMany(features);
} catch (error) {
if (!controller.signal.aborted) {
console.error(error);
this.textContent = "Could not load trace results.";
}
} finally {
if (this.#controller === controller) {
this.#controller = undefined;
this.dispatchEvent(new CustomEvent("arcgisResultReady"));
}
}
}
clearResult(): void {
this.#controller?.abort();
this.#controller = undefined;
this.#view?.graphics.removeMany(this.#graphics);
this.#view = undefined;
this.#graphics = [];
this.replaceChildren();
}
}

clearResult aborts an in-flight query; its canceled work does not emit arcgisResultReady. The sample's extent query is illustrative; use a query appropriate to the trace result in your component.