import type Analysis from "./Analysis.js";
import type DimensionSimpleStyle from "./DimensionSimpleStyle.js";
import type LengthDimension from "./LengthDimension.js";
import type Collection from "../core/Collection.js";
import type { LengthDimensionProperties } from "./LengthDimension.js";
import type { ReadonlyArrayOrCollection } from "../core/Collection.js";
import type { DimensionSimpleStyleProperties } from "./DimensionSimpleStyle.js";
import type { AnalysisProperties } from "./Analysis.js";

export interface DimensionAnalysisProperties extends AnalysisProperties {
  /** A list of dimensions. */
  dimensions?: ReadonlyArrayOrCollection<LengthDimensionProperties>;
  /** The style defines how the dimension objects of this analysis are displayed. */
  style?: (DimensionSimpleStyleProperties & { type: "simple" });
}

/**
 * DimensionAnalysis enables the creation and display of measurement annotations for lengths and distances in a 3D
 * [SceneView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html).
 *
 * The analysis can contain multiple dimensions. These can be created interactively or programmatically, and the analysis can be added directly to either
 * [SceneView.analyses](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html#analyses) or to the
 * [DimensionLayer.source](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-DimensionLayer.html#source) in a [SceneView.map](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html#map).
 *
 * ```js
 * // create analysis with dimensions
 * const dimensionAnalysis = new DimensionAnalysis({
 *   dimensions: [
 *     new LengthDimension({
 *       startPoint: new Point({ }),
 *       endPoint: new Point({ })
 *     })
 *   ],
 *   style: new DimensionSimpleStyle({
 *     color: "white"
 *   }),
 * });
 *
 * // add the analysis to the view
 * view.analyses.add(dimensionAnalysis);
 * ```
 *
 * Use the [DimensionAnalysisView3D](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-DimensionAnalysisView3D.html) to retrieve the analysis results.
 *
 * ```js
 * // retrieve measured results from the analysis view
 * const analysisView = await view.whenAnalysisView(dimensionAnalysis);
 * const results = analysisView.results;
 * ```
 *
 * To place a length dimension interactively, use the
 * [DimensionAnalysisView3D.place()](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-DimensionAnalysisView3D.html#place) method.
 *
 * ```js
 * const abortController = new AbortController();
 *
 * try {
 *   await analysisView.place({ signal: abortController.signal });
 * } catch (error) {
 *   if (error.name === "AbortError") {
 *     console.log("Placement operation was cancelled.");
 *   }
 * }
 *
 * // cancel the placement operation at some later point
 * abortController.abort();
 * ```
 *
 * To edit existing dimensions interactively, set the
 * [DimensionAnalysisView3D.interactive](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-DimensionAnalysisView3D.html#interactive) property
 * `true` and select a dimension by hovering and clicking on their offset manipulator.
 *
 * ```js
 * // allow existing dimensions in the analysis to be selected and edited
 * analysisView.interactive = true;
 * ```
 *
 * DimensionAnalysis can be saved to a [WebScene](https://developers.arcgis.com/javascript/latest/api-reference/esri-WebScene.html) as part of a [DimensionLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-DimensionLayer.html).
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > This analysis is only supported in a 3D [SceneView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html).
 *
 * @since 4.25
 * @see [DimensionAnalysisView3D](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-analysis-DimensionAnalysisView3D.html)
 * @see [LengthDimension](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-LengthDimension.html)
 * @see [DimensionSimpleStyle](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-DimensionSimpleStyle.html)
 * @see [DimensionLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-DimensionLayer.html)
 * @see [DimensionLayerView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-layers-DimensionLayerView.html)
 * @see [Sample - Length dimensioning](https://developers.arcgis.com/javascript/latest/sample-code/layers-dimension/)
 * @see [Sample - Analysis objects](https://developers.arcgis.com/javascript/latest/sample-code/analysis-objects/)
 */
export default class DimensionAnalysis extends Analysis {
  constructor(properties?: DimensionAnalysisProperties);
  /** A list of dimensions. */
  get dimensions(): Collection<LengthDimension>;
  set dimensions(value: ReadonlyArrayOrCollection<LengthDimensionProperties>);
  /** The style defines how the dimension objects of this analysis are displayed. */
  get style(): DimensionSimpleStyle;
  set style(value: (DimensionSimpleStyleProperties & { type: "simple" }));
  /** The type of analysis. For dimension analysis, this is always "dimension". */
  get type(): "dimension";
  /**
   * Indicates whether the analysis is ready to be computed and interacted with in the view.
   * It requires each of the [dimensions](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-DimensionAnalysis.html#dimensions) to be valid, that is, to have both a start and end point
   * If the analysis has no dimension, it is considered valid.
   *
   * @since 4.33
   */
  get valid(): boolean;
  /**
   * Clears the analysis by removing all [dimensions](https://developers.arcgis.com/javascript/latest/api-reference/esri-analysis-DimensionAnalysis.html#dimensions).
   *
   * @since 5.0
   */
  clear(): void;
}