import type Accessor from "../../../core/Accessor.js";
import type SketchTooltipVisibleElements from "./SketchTooltipVisibleElements.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { SketchTooltipVisibleElementsProperties } from "./SketchTooltipVisibleElements.js";

export interface SketchTooltipOptionsProperties extends Partial<Pick<SketchTooltipOptions, "enabled" | "forceEnabled" | "helpMessage" | "helpMessageIcon" | "inputEnabled">> {
  /** The elements that are displayed within the tooltip while sketching. */
  visibleElements?: SketchTooltipVisibleElementsProperties;
}

/**
 * The `SketchTooltipOptions` allows users to configure the tooltips which are shown while
 * sketching and editing.
 *
 * To enter the tooltip UI's [input mode](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/sketch/SketchTooltipOptions/#inputEnabled),
 * press the `Tab` key while drawing a new feature, or when editing a point, mesh, or a selected vertex.
 *
 * [<video src="https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/editor/editing-constraints.webm" aria-label="sketch-3d-with-constraints" autoplay muted playsinline loop></video>](https://developers.arcgis.com/javascript/latest/sample-code/sketch-3d/)
 *
 * #### Available tooltip inputs and constraints
 *
 * **Direction** field and its respective constraint controls the direction (angle) of a segment (applies to polylines/polygons while drawing).\
 *    It has two options that can be set either in the tooltip's UI or with
 *    [valueOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/sketch/SketchValueOptions/):
 *    - **Deflection** – **relative** angle that is measured from the previous segment (default).
 *       Positive values are measured in a clockwise direction. Negative values are measured in a counterclockwise direction.
 *    - **Direction** – **absolute** angle that is measured clockwise from the main axis of the map (typically north).
 *
 * **Distance** field and its respective constraint controls the length of a segment (applies to polylines/polygons while drawing). Distance field is also shown
 *    when editing an edge offset in SceneView.
 *
 * **Coordinates** fields edit the longitude and latitude (in geographic coordinate systems and
 *    in Web Mercator) or X and Y values (in projected coordinate systems) of a point or a vertex
 *    of a polyline/polygon.\
 *    The coordinates can be entered as separate values or as a latitude+longitude pair. In case of the latter,
 *    the pair can be typed or pasted into either of the two coordinate fields and the input is converted to decimal degree format.
 *    The coordinates may use DD (decimal degrees), DDM (degrees and decimal minutes), or DMS (degrees, minutes, and seconds) format.
 *    See more about [supported latitude/longitude strings](https://developers.arcgis.com/javascript/latest/references/core/geometry/coordinateFormatter/#fromLatitudeLongitude).
 *
 * **Elevation (Z)** field and its respective constraint edits the Z value of a point or a vertex of a polyline/polygon geometry.\
 *    When drawing polygon or polyline segments, the Z (elevation) field is locked by default.
 *    This means that all vertices use the Z value of the first vertex. The constraint can be unlocked in the tooltips' input mode.
 *
 * **Orientation** field edits the orientation of a mesh. The angle is measured clockwise from the main axis
 *    of the map (typically north).\
 *    Note that the orientation field is connected to the mesh geometry's
 *    [rotation transform](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshTransform/#rotationAngle) property.
 *    The latter is an arithmetic rotation which is measured counterclockwise from the 3 o'clock position (typically east).
 *
 * **Scale** field edits the scale of a mesh.
 *
 * *The following fields are read-only: **Total length** (for polylines only), **Area** (for polygons only),
 * or fields shown when dragging the manipulators, such as relative **Distance**, **Radius**, relative **Rotation**, relative **Scale**, and **Size**.*
 *
 * ##### Considerations when using distance, direction, and deflection constraints
 *
 * - In geographic coordinate systems (GCS) and in Web Mercator, the constraints are computed geodetically.
 * - In projected coordinate systems (PCS), apart from Web Mercator, the constraints are computed in a Euclidean manner (in the respective PCS).
 * - In 3D, the distance, direction, and deflection constraints are computed on a horizontal plane, dependent on the view's spatial reference.
 *
 * #### Available gestures
 *
 * Gesture | Action |
 * ---------|---------|
 * `Tab` | Activates the input mode and focuses on the next field. |
 * Input value + `Tab` | Applies the constraint and focuses on the next field.  |
 * Empty value + `Tab` | Removes the constraint and focuses on the next field.  |
 * Input value + `Enter` | Applies the constraint and closes the input mode.  |
 * Empty value + `Enter` | Removes the constraint and closes the input mode.  |
 * Lock icon | Toggles the constraint on and off. |
 * `Esc` | Closes the input mode but keeps any applied constraints. |
 * Left-click-drag (on tooltip header) | Allows to change the position of the tooltip in input mode. |
 *
 * @since 4.24
 * @see [Sketch](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/)
 * @see [SketchViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/SketchViewModel/)
 * @see [SketchLabelOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/sketch/SketchLabelOptions/)
 * @see [SketchValueOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/sketch/SketchValueOptions/)
 * @see [Editor](https://developers.arcgis.com/javascript/latest/references/core/widgets/Editor/)
 * @see [Sample - Sketch in 3D](https://developers.arcgis.com/javascript/latest/sample-code/sketch-3d/)
 * @see [Sample - Edit features in 3D with the Editor widget](https://developers.arcgis.com/javascript/latest/sample-code/editor-3d/)
 */
export default class SketchTooltipOptions extends Accessor {
  constructor(properties?: SketchTooltipOptionsProperties);
  /**
   * Effective value of `enabled` considering the state of `forceEnabled`.
   *
   * @internal
   */
  get effectiveEnabled(): boolean;
  /**
   * Whether tooltips are shown while sketching and editing.
   *
   * @default false
   */
  accessor enabled: boolean;
  /**
   * Temporary override option for `enabled`. Can for example be used to allow a keybinding to
   * temporarily show the tooltips.
   *
   * @default false
   * @internal
   */
  accessor forceEnabled: boolean;
  /**
   * A custom help message that is displayed at the bottom of the tooltip. If not set, the default
   * help message based on the current state of the tool is shown.
   */
  accessor helpMessage: string | null | undefined;
  /**
   * An icon that is displayed next to the help message at the bottom of the tooltip. If not set,
   * the default info icon is shown.
   */
  accessor helpMessageIcon: Icon["icon"] | null | undefined;
  /**
   * Whether users can focus the tooltip and input constraint values.
   *
   * @default true
   */
  accessor inputEnabled: boolean;
  /** The elements that are displayed within the tooltip while sketching. */
  get visibleElements(): SketchTooltipVisibleElements;
  set visibleElements(value: SketchTooltipVisibleElementsProperties);
}