@arcgis/map-components 5.0.0-next.14 → 5.0.0-next.140

package/dist/components/arcgis-volume-measurement/customElement.d.ts

@@ -0,0 +1,384 @@
+/// <reference path="../../index.d.ts" />
+import type SceneView from "@arcgis/core/views/SceneView.js";
+import type VolumeMeasurementAnalysis2 from "@arcgis/core/analysis/VolumeMeasurementAnalysis.js";
+import type { PublicLitElement as LitElement } from "@arcgis/lumina/PublicLitElement";
+import type { ArcgisReferenceElement } from "../../utils/component-utils.js";
+import type { HeadingLevel } from "../../support/heading.js";
+import type { VolumeMeasureType } from "@arcgis/core/analysis/VolumeMeasurement/types";
+import type { T9nMeta } from "@arcgis/lumina/controllers";
+import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
+import type { SystemOrVolumeUnit, SystemOrLengthUnit, LengthUnit, SystemOrAreaUnit } from "@arcgis/core/core/units.js";
+
+/**
+ * The Volume Measurement component can be added to a
+ * [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/) to
+ * calculate and visualize the volume of ground surfaces within a defined polygonal area.
+ *
+ * [![measurement-volume](https://developers.arcgis.com/javascript/latest/assets/img/components/volume-measurement/volume_measurement_poster.png)](https://developers.arcgis.com/javascript/latest/sample-code/analysis-volume-measurement/)*
+ *
+ * Volume Measurement component offers multiple volume measurement modes:
+ *
+ * - **Cut & Fill Volume**: Computes cut and fill volumes relative to a flat, horizontal surface defined by the input
+ * polygon. Ideal for estimating the amount of material to remove or add to level terrain for construction.
+ *
+ * - **Stockpile Volume**: Calculates cut and fill volumes against a surface approximated from the polygon's coordinates.
+ * Useful for estimating the volume of temporary ground features such as piles of material, mounds or depressions.
+ *
+ * The analysis depends on the scene's spatial reference, and the length of the measured perimeter:
+ *
+ * - In **Projected Coordinate Systems (PCS)**, apart from Web Mercator used in **local** viewing mode, there is no limit
+ * to the measurement's perimeter, making it the recommended setup for analysis as accuracy is not compromised.
+ *
+ * - In **Web Mercator PCS** used in **local** viewing mode, if the measurement's perimeter exceeds 10 km, the analysis is considered invalid due to potential accuracy issues.
+ *
+ * - In **Geographic Coordinate Systems (GCS)** and **Web Mercator** in **global** viewing mode, if the measurement's perimeter exceeds 50 km, the analysis is considered invalid due to potential accuracy issues.
+ *
+ *
+ * **Known Limitations**
+ *
+ * -  Volume Measurement component can only be added to a
+ * [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/) component.
+ * - The results of the tool vary depending on the zoom level, as changes in zoom level affect the level of detail (LOD) of the scene geometry.
+ * - If the view is too close or too far from the measurement polygon, the results will not be computed due to LOD-induced inaccuracies.
+ * - The elevation of the target surface in the "Cut & Fill Volume" mode is restricted to the range of -11 km and +9 km.
+ * - This tool operates only on the non-transparent [Map.ground](https://developers.arcgis.com/javascript/latest/api-reference/esri-Map.html#ground),
+ * [IntegratedMeshLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-IntegratedMeshLayer.html)
+ * and an [IntegratedMesh3DTilesLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-IntegratedMesh3DTilesLayer.html).
+ * - This tool does not support WGS 1984 spatial reference in a local
+ * [viewing mode](https://developers.arcgis.com/javascript/latest/api-reference/esri-webscene-InitialViewProperties.html#viewingMode).
+ *
+ * **Things to consider**
+ *
+ * - In "Cut & Fill Volume" mode, you can hover over the shift manipulator, press `Tab` to enable tooltip input,
+ * and enter the target surface elevation.
+ * - Snapping is enabled by default. This can be temporarily disabled by holding the `CTRL` key.
+ * - Layer types currently supported for snapping are:
+ * [FeatureLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-FeatureLayer.html),
+ * [GraphicsLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-GraphicsLayer.html) (except Mesh geometries),
+ * [GeoJSONLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-GeoJSONLayer.html),
+ * [WFSLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-WFSLayer.html),
+ * [CSVLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-CSVLayer.html),
+ * [3D Object SceneLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-SceneLayer.html),
+ * and [BuildingSceneLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-BuildingSceneLayer.html).
+ *
+ * **See also**
+ *
+ * - [Volume Measurement Analysis](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-VolumeMeasurementAnalysis.html)
+ * - [VolumeMeasurementAnalysisView3D](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-VolumeMeasurementAnalysisView3D.html)
+ * - [VolumeMeasurementCutFillOptions](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-VolumeMeasurement-VolumeMeasurementCutFillOptions.html)
+ * - [VolumeMeasurementResult](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-VolumeMeasurement-VolumeMeasurementResult.html)
+ * - [VolumeMeasurementDisplayUnits](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-VolumeMeasurement-VolumeMeasurementDisplayUnits.html)
+ * - [VolumeMeasurementInputUnits](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-VolumeMeasurement-VolumeMeasurementInputUnits.html)
+ * - [VolumeMeasurementError](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-VolumeMeasurement-VolumeMeasurementError.html)
+ * - [Sample - Volume measurement analysis object](https://developers.arcgis.com/javascript/latest/sample-code/analysis-volume-measurement/)
+ *
+ * @since 5.0
+ */
+export abstract class ArcgisVolumeMeasurement extends LitElement {
+  /**
+   * The [VolumeMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-VolumeMeasurementAnalysis.html)
+   * created or modified by the component.
+   *
+   * When connecting the Volume Measurement component to the [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/)
+   * component, it automatically creates an empty analysis and adds it to the Scene's
+   * [analyses](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#analyses) collection.
+   * Whenever the component is destroyed, the analysis is automatically removed from the collection.
+   *
+   * Alternatively, a programmatically created analysis can be provided to the component.
+   * Then, the application itself needs to add it to and later remove it from the Scene's analyses collection.
+   *
+   * ```js
+   * // Create the analysis.
+   * const volumeMeasurementAnalysis = new VolumeMeasurementAnalysis({
+   *    geometry: new Polygon({
+   *      spatialReference: { latestWkid: 3857, wkid: 102100 },
+   *      rings: [
+   *        [
+   *          [-13624861.22274897, 4550346.5519295, 63.378210234455764],
+   *          [-13624935.305160372, 4550273.144585712, 63.37829629518092],
+   *          [-13624995.61798748, 4550334.030096778, 63.37819860037416],
+   *          [-13624921.53589075, 4550407.42357004, 63.3783810287714],
+   *          [-13624861.22274897, 4550346.5519295, 63.378210234455764]
+   *        ]
+   *      ]
+   *    })
+   * });
+   * // Get the Scene and measurement component and wait until they are ready.
+   * const viewElement = document.querySelector("arcgis-scene");
+   * await viewElement.viewOnReady();
+   * const volumeMeasurementElement = document.querySelector("arcgis-volume-measurement");
+   * await volumeMeasurementElement.componentOnReady();
+   * // Add the analysis to the Scene component.
+   * viewElement.analyses.add(volumeMeasurementAnalysis);
+   * // Connect the analysis to the measurement component:
+   * volumeMeasurementElement.analysis = volumeMeasurementAnalysis;
+   * ```
+   *
+   * @since 5.0
+   */
+  accessor analysis: VolumeMeasurementAnalysis2;
+  /**
+   * Unit system (imperial, metric) or specific unit used for displaying the area. Possible values are listed in
+   * [areaDisplayUnitOptions](#areaDisplayUnitOptions).
+   *
+   * @since 5.0
+   */
+  accessor areaDisplayUnit: SystemOrAreaUnit;
+  /**
+   * List of available units and unit systems (imperial, metric) that are shown in the component's area display unit dropdown.
+   * By default, the following units are included: `metric`, `imperial`, `square-inches`, `square-feet`, `square-yards`, `square-miles`, `square-nautical-miles`, `square-us-feet`, `square-millimeters`, `square-centimeters`, `square-decimeters`, `square-meters`, `square-kilometers`, `acres`, `ares`, `hectares`.
+   * Possible [areaDisplayUnit](#areaDisplayUnit) values can only be a subset of this list.
+   *
+   * @since 5.0
+   */
+  accessor areaDisplayUnitOptions: Array<SystemOrAreaUnit>;
+  /**
+   * 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/arcgis-volume-measurement/#destroy) method when you are done to
+   * prevent memory leaks.
+   *
+   * @default false
+   */
+  accessor autoDestroyDisabled: boolean;
+  /**
+   * Unit system (imperial, metric) or specific unit used for displaying the cut and fill target elevation. Possible values are listed in
+   * [elevationDisplayUnitOptions](#elevationDisplayUnitOptions).
+   *
+   * @since 5.0
+   */
+  accessor elevationDisplayUnit: SystemOrLengthUnit;
+  /**
+   * List of available units and unit systems (imperial, metric) that are shown in the component's dropdown.
+   * By default, the following units are included: `metric`, `imperial`, `meters`, `millimeters`, `centimeters`, `decimeters`, `kilometers`, `inches`, `feet`, `yards`, `miles`, `nautical-miles`, `us-feet`.
+   * Possible [elevationDisplayUnit](#elevationDisplayUnit) values can only be a subset of this list.
+   *
+   * @since 5.0
+   */
+  accessor elevationDisplayUnitOptions: Array<SystemOrLengthUnit>;
+  accessor elevationInputUnit: LengthUnit;
+  accessor elevationInputUnitOptions: Array<LengthUnit>;
+  /**
+   * Indicates the heading level to use for the headings in the component.
+   *
+   * @default 2
+   */
+  accessor headingLevel: HeadingLevel;
+  /**
+   * Hides the area display unit dropdown.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideAreaDisplayUnitSelect: boolean;
+  /**
+   * Hides the elevation display unit dropdown.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideElevationDisplayUnitSelect: boolean;
+  /**
+   * Hides the elevation input unit dropdown.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideElevationInputUnitSelect: boolean;
+  /**
+   * Hides the header.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideHeader: boolean;
+  /**
+   * Hides the mode selection dropdown.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideModeSelect: boolean;
+  /**
+   * Hides the perimeter display unit dropdown.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hidePerimeterDisplayUnitSelect: boolean;
+  /**
+   * Hides the unit settings button.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideUnitSettings: boolean;
+  /**
+   * Indicates whether the component's visualization is hidden in the view.
+   *
+   * @default false
+   */
+  accessor hideVisualization: boolean;
+  /**
+   * Hides the volume display unit dropdown.
+   *
+   * @default false
+   * @since 5.0
+   */
+  accessor hideVolumeDisplayUnitSelect: boolean;
+  /**
+   * Icon which represents the component.
+   * Typically used when the component is controlled by another component (e.g. by the Expand component).
+   *
+   * @default "measure-area"
+   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
+   */
+  accessor icon: Icon["icon"] | undefined;
+  /** The component's default label. */
+  accessor label: string | undefined;
+  /** @internal */
+  protected messages: {
+      componentLabel: string;
+      title: string;
+      hint: string;
+      measurementMode: string;
+      newMeasurement: string;
+      cutAndFillMode: string;
+      stockpileMode: string;
+      cutVolume: string;
+      totalVolume: string;
+      fillVolume: string;
+      netVolume: string;
+      perimeter: string;
+      area: string;
+      snappingDisablePrompt: string;
+      snappingDisablePromptAlternate: string;
+      displaySettings: string;
+      unsupported: string;
+      errorDistanceTooFar: string;
+      errorDistanceTooClose: string;
+      errorPerimeterTooLarge: string;
+      errorUnsupportedCoordinateSystem: string;
+      errorUnsupportedLayerTransparency: string;
+      errorUnknown: string;
+      inputUnits: string;
+      displayUnits: string;
+      elevationInputUnit: string;
+      elevationDisplayUnit: string;
+      volumeDisplayUnit: string;
+      areaDisplayUnit: string;
+      perimeterDisplayUnit: string;
+  } & T9nMeta<{
+      componentLabel: string;
+      title: string;
+      hint: string;
+      measurementMode: string;
+      newMeasurement: string;
+      cutAndFillMode: string;
+      stockpileMode: string;
+      cutVolume: string;
+      totalVolume: string;
+      fillVolume: string;
+      netVolume: string;
+      perimeter: string;
+      area: string;
+      snappingDisablePrompt: string;
+      snappingDisablePromptAlternate: string;
+      displaySettings: string;
+      unsupported: string;
+      errorDistanceTooFar: string;
+      errorDistanceTooClose: string;
+      errorPerimeterTooLarge: string;
+      errorUnsupportedCoordinateSystem: string;
+      errorUnsupportedLayerTransparency: string;
+      errorUnknown: string;
+      inputUnits: string;
+      displayUnits: string;
+      elevationInputUnit: string;
+      elevationDisplayUnit: string;
+      volumeDisplayUnit: string;
+      areaDisplayUnit: string;
+      perimeterDisplayUnit: string;
+  }>;
+  /**
+   * Specifies the analysis' desired measurement type.
+   *
+   * @since 5.0
+   */
+  accessor mode: VolumeMeasureType;
+  /**
+   * Unit system (imperial, metric) or specific unit used for displaying the area. Possible values are listed in
+   * [areaDisplayUnitOptions](#areaDisplayUnitOptions).
+   *
+   * @since 5.0
+   */
+  accessor perimeterDisplayUnit: SystemOrLengthUnit;
+  /**
+   * List of available units and unit systems (imperial, metric) that are shown in the component's area display unit dropdown.
+   * By default, the following units are included: `metric`, `imperial`, `meters`, `millimeters`, `centimeters`, `decimeters`, `kilometers`, `inches`, `feet`, `yards`, `miles`, `nautical-miles`, `us-feet`.
+   * Possible [areaDisplayUnit](#areaDisplayUnit) values can only be a subset of this list.
+   *
+   * @since 5.0
+   */
+  accessor perimeterDisplayUnitOptions: Array<SystemOrLengthUnit>;
+  /**
+   * 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;
+  /**
+   * The component's state. The values mean the following:
+   *
+   * * `disabled` -  not ready yet
+   * * `ready` - ready for measuring
+   * * `measuring` - currently measuring
+   * * `measured` - measuring has finished
+   *
+   * @since 5.0
+   */
+  get state(): "disabled" | "ready" | "measured" | "measuring";
+  /**
+   * 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 Volume Measurement component will be associated with a map or scene component rather than using the `view` property.
+   */
+  accessor view: SceneView | undefined;
+  /**
+   * Unit system (imperial, metric) or specific unit used for displaying the volume values. Possible values are listed in
+   * [volumeDisplayUnitOptions](#volumeDisplayUnitOptions).
+   *
+   * @since 5.0
+   */
+  accessor volumeDisplayUnit: SystemOrVolumeUnit;
+  /**
+   * List of available units and unit systems (imperial, metric) that are shown in the component's dropdown.
+   * By default, the following units are included: `imperial`, `metric`, `liters`, `cubic-millimeters`, `cubic-centimeters`, `cubic-decimeters`, `cubic-meters`, `cubic-kilometers`, `cubic-inches`, `cubic-feet`, `cubic-yards`, `cubic-miles`.
+   * Possible [volumeDisplayUnit](#volumeDisplayUnit) values can only be a subset of this list.
+   *
+   * @since 5.0
+   */
+  accessor volumeDisplayUnitOptions: Array<SystemOrVolumeUnit>;
+  /**
+   * Clears the current measurement.
+   *
+   * @since 5.0
+   */
+  clear(): Promise<void>;
+  /** Permanently destroy the component. */
+  destroy(): Promise<void>;
+  /**
+   * Starts a new measurement.
+   *
+   * @since 5.0
+   */
+  start(): 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: "analysis" | "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: ArcgisVolumeMeasurement["arcgisPropertyChange"]["detail"];
+    arcgisReady: ArcgisVolumeMeasurement["arcgisReady"]["detail"];
+  };
+}