@arcgis/map-components/dist/components/arcgis-directions/customElement.d.ts

ArcGIS Map Components

/// <reference path="../../index.d.ts" />
import type RouteLayer from "@arcgis/core/layers/RouteLayer.js";
import type PortalItem from "@arcgis/core/portal/PortalItem.js";
import type PortalFolder from "@arcgis/core/portal/PortalFolder.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName } from "../types.js";
import type { RouteLayerSolveResult } from "@arcgis/core/layers/types.js";
import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js";
import type { GoToOverride, HeadingLevel } from "@arcgis/core/widgets/support/types.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { SearchProperties } from "@arcgis/core/widgets/Search.js";
import type { State } from "@arcgis/core/widgets/Directions/DirectionsViewModel.js";
import type { SystemOrLengthUnit } from "@arcgis/core/core/units.js";

/**
 * The Directions component provides a way to calculate directions, between two or more input locations with a [RouteLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/), using ArcGIS Online and custom Network Analysis Route services.
 * This component generates a route finding a least-cost path between multiple points using the routing service associated with the assigned RouteLayer. The route is calculated based on the stops and barriers added to the RouteLayer. The component provides a user interface for adding, removing, and reordering stops and barriers. Once the route is solved, the component displays the route on the map and provides turn-by-turn directions in a list format.
 *
 * Directions uses the [Search component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/) to locate each stop, either by selecting a point on the map, or by entering a search term into the textbox.
 * Search uses settings defined in the `Search properties`. This includes the `locationType`, which defines the type of geocoding result that is returned, and defaults to "street".
 *
 * Directions requires a RouteLayer to be associated with the `layer` property or using the `useDefaultRouteLayer` property. A RouteLayer can be programmatically created or derived from an external source like a portal item or webmap.
 * Please note that in order to view or interact with routing inputs and results, the RouteLayer must be added to the map. Routing service and symbology is configured in the layer, specifically the `url` and `defaultSymbols` properties respectively.
 *
 * The ArcGIS Online routing service requires authentication. If an API key is specified at the app level (see [Config#apiKey](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey)) or component level (see [apiKey](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#apiKey))) then this key will accompany requests to both the routing service and geocoder/reverse-geocoder.
 * Please refer to the Search component for more information on geocoding.
 *
 * Locations on the map can be reverse geocoded and used as stops in the route. Click the button with a crosshairs icon to associate a location with a new or existing stop.  After clicking the button, click the map once. To cancel this process, press the `escape` key.
 * The resulting driving directions are automatically collapsed and can be optionally saved to a new or existing portal item. This can be achieved programically with `save` and `saveAs`. The `Clear` button calls the `reset()` method, which removes all stops, directions, and the solved route.
 *
 * Selecting the `Edit route` button allows you to add/move/remove stops, add/move/remove/reshape polyline barriers, and add/move/remove waypoints. To add a new waypoint, first hover the cursor over the route and select the desired point. Then select and drag the point to move and place the waypoint. By default the route will be automatically resolve at the completion of any editing operation. For more complex routes, it may be advantageous to disable auto-solving and solve as and when needed with the dedicated solve button. Currently, this is only supported in 2D MapViews.
 *
 * **Note:** Printing in Directions is in beta and considered experimental. The print preview dialog, in some scenarios, may not display as aniticipated.
 *
 * @see [Sample - Directions component with RouteLayer](https://developers.arcgis.com/javascript/latest/sample-code/directions-routelayer/)
 * @since 4.28
 */
export abstract class ArcgisDirections extends LitElement {
  /**
   * An authorization string used to access a resource or service.
   * [API keys](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/) are generated
   * and managed in the portal. An API key is tied
   * explicitly to an ArcGIS account; it is also used to monitor service usage.
   * Setting a fine-grained API key on a specific class overrides the [global API key](https://developers.arcgis.com/javascript/latest/references/core/config/#ConfigWithApiKey).
   *
   * By default, the following URLs will be used (unless overwritten in the app, or if using different defaults from a portal):
   *
   * Geocoding URL: `https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer`
   *
   * Routing URL: `https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World`
   *
   * @since 4.19
   * @example
   * // Add the Directions component to the top right corner of the view component
   * <arcgis-map>
   *   <arcgis-directions api-key="YOUR_API_KEY" slot="top-right"></arcgis-directions>
   * </arcgis-map>
   */
  accessor apiKey: string | null | undefined;
  /**
   * If true, the component will not be destroyed automatically when it is
   * disconnected from the document. This is useful when you want to move the
   * component to a different place on the page, or temporarily hide it. If this
   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#destroy) method when you are done to
   * prevent memory leaks.
   *
   * @default false
   */
  accessor autoDestroyDisabled: boolean;
  /**
   * When `true`, the route will re-solve continuously as an interactive operation is ongoing (e.g., while dragging a stop or waypoint).
   *
   * @default false
   * @since 5.0
   */
  accessor autoSolveOnEditActive: boolean;
  /**
   * This function provides the ability to override either the [arcgis-map.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#goTo) or [arcgis-scene.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#goTo) methods.
   *
   * @since 4.33
   * @example
   * ```js
   * component.goToOverride = function(view, goToParams) {
   *   goToParams.options = {
   *     duration: updatedDuration
   *   };
   *   return view.goTo(goToParams.target, goToParams.options);
   * };
   * ```
   */
  accessor goToOverride: GoToOverride | null | undefined;
  /**
   * Indicates the heading level to use for the origin and destination addresses (i.e. "380 New York Street").
   * By default, this is rendered
   * as a level 2 heading (e.g. `<h2>380 New York Street</h2>`). Depending on the component's placement
   * in your app, you may need to adjust this heading for proper semantics. This is
   * important for meeting accessibility standards.
   *
   * @default 2
   * @since 4.20
   * @see [Heading Elements](https://developer.mozilla.org/docs/Web/HTML/Element/Heading_Elements)
   * @example
   * // address text will render as an <h3>
   * directions.headingLevel = 3;
   */
  accessor headingLevel: HeadingLevel;
  /**
   * Indicates whether to a link to the route layer portal-item (if any) will be displayed
   *
   * @default false
   * @since 5.0
   */
  accessor hideLayerDetails: boolean;
  /**
   * Indicates whether to the Print button will be displayed
   *
   * @default false
   * @since 5.0
   */
  accessor hidePrintButton: boolean;
  /**
   * Indicates whether to the Save As button will be displayed
   *
   * @default false
   * @since 5.0
   */
  accessor hideSaveAsButton: boolean;
  /**
   * Indicates whether to the Save button will be displayed
   *
   * @default false
   * @since 5.0
   */
  accessor hideSaveButton: boolean;
  /**
   * Icon which represents the component.
   * Typically used when the component is controlled by another component (e.g. by the Expand component).
   *
   * @default "right"
   * @since 4.27
   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: IconName);
  /**
   * The component's default label.
   *
   * @since 4.7
   */
  accessor label: string;
  /**
   * The most recent route result. Returns a [RouteLayerSolveResult](https://developers.arcgis.com/javascript/latest/references/core/layers/types/#RouteLayerSolveResult)
   * object containing properties for barriers (if any), stops, and directions.
   *
   * @see [RouteLayer#solve()](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/#solve)
   */
  get lastRoute(): RouteLayerSolveResult | null | undefined;
  /**
   * The [RouteLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/) associated with the Directions component.
   * A RouteLayer must be associated with the component in order to solve routes and display results on the map.
   *
   * The RouteLayer can be set directly via the `layer` property, or indirectly by setting either the [mapLayerId](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#mapLayerId) or [routeLayerItemId](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#routeLayerItemId) properties.
   * If using the latter, the component will attempt to find and use a layer matching the provided ID from the map or portal item.
   * If no layer is found and [useDefaultRouteLayer](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#useDefaultRouteLayer) is not set to `true`, then no RouteLayer will be associated and routing functionality will be unavailable.
   * The RouteLayer contains stops and barriers and will be used to display and solve routes.
   *
   * > [!WARNING]
   * > Use `layer`, `mapLayerId`, and `routeLayerItemId` independently; only one should be set at a time.
   */
  accessor layer: RouteLayer | null | undefined;
  /**
   * The layer ID of a route layer in the associated map.
   * When set, the component will attempt to find and use the layer with the provided ID from the map.
   *
   * > [!WARNING]
   * > Use `layer`, `mapLayerId`, and `routeLayerItemId` independently; only one should be set at a time.
   *
   * @since 5.1
   * @example
   * ```html
   * <arcgis-map item-id="28c1e2519ee44e93b42c8adbee0d4dd0">
   *  <arcgis-directions slot="top-right" map-layer-id="19e2cba6c23-layer-2"></arcgis-directions>
   * </arcgis-map>
   * ```
   */
  accessor mapLayerId: string | undefined;
  /**
   * The maximum number of stops allowed for routing.
   *
   * @default 50
   */
  accessor maxStops: 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.
   *
   * @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)
   */
  accessor referenceElement: ArcgisReferenceElement | string | undefined;
  accessor routeLayerItemId: string | undefined;
  /**
   * Controls the default properties used when searching.
   * Note that the default `searchProperties` differ slightly from
   * the [Search component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/).
   *
   * @default { popupEnabled: false, resultGraphicEnabled: false }
   */
  accessor searchProperties: SearchProperties | null | undefined;
  /**
   * The current state of the component.
   *
   * @default "disabled"
   */
  get state(): State;
  /**
   * Unit system (imperial, metric) or specific unit used for displaying the distance values.
   * If not set, the component will attempt to pick "imperial" or "metric" based on the user's portal settings.
   *
   * This property will affect the summary distance as well as distance for each turn-by-turn maneuver.
   *
   * @since 4.25
   * @example
   * // Display distances in nautical miles.
   * const directions = new Directions({
   *   unit: "nautical-miles",
   *   layer: routeLayer,
   *   view: view
   * });
   */
  accessor unit: SystemOrLengthUnit;
  /**
   * If `true`, a new [RouteLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/) will be created, added to the map and assigned to the `layer` property.
   *
   * @default false
   */
  accessor useDefaultRouteLayer: boolean;
  /**
   * 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-directions component will be associated with a map or scene component rather than using the `view` property.
   */
  accessor view: MapViewOrSceneView | null | undefined;
  /** Permanently destroy the component. */
  destroy(): Promise<void>;
  /** Computes a route and directions. If successfully computed, results will be assigned to the [lastRoute](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#lastRoute) property. */
  getDirections(): Promise<RouteLayerSolveResult>;
  /**
   * Saves the currently assigned [RouteLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/)
   * (see [layer](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#layer)) to an existing portal item.
   */
  save(): Promise<PortalItem>;
  /**
   * Saves the currently assigned [RouteLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/)
   * (see [layer](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/#layer)) to a new portal item.
   *
   * @param portalItem
   * @param options
   */
  saveAs(portalItem: PortalItem, options: { folder: PortalFolder; }): Promise<PortalItem>;
  /** Starts an edit session for interactive addition, modification, and deletion of stops, barriers, and waypoints. */
  startEditing(): Promise<void>;
  /** Ends an interactive edit session. */
  stopEditing(): Promise<void>;
  /** Zoom so that the entire route is displayed within the current map extent. */
  zoomToRoute(): Promise<void>;
  "@setterTypes": {
    icon?: IconName;
  };
  /** 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: "lastRoute" | "state"; }>;
  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly "@eventTypes": {
    arcgisPropertyChange: ArcgisDirections["arcgisPropertyChange"]["detail"];
    arcgisReady: ArcgisDirections["arcgisReady"]["detail"];
  };
}