import type { JSONSupport } from "../core/JSONSupport.js";

export interface ExpressionInfoProperties extends Partial<Pick<ExpressionInfo, "expression" | "name" | "returnType" | "title">> {}

/**
 * The `ExpressionInfo` class references [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expressions following
 * the specification defined by the [Arcade Popup Profile](https://developers.arcgis.com/javascript/latest/arcade/#popup).
 * Expressions must return a string or a number and may access data values from the feature, its layer, or other layers
 * in the map or datastore with the `$feature`, `$layer`, `$map`, and `$datastore` profile variables.
 *
 * Expression names are referenced in a layer's [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html) and execute once a layer's popup is opened.
 * The values display within the view's popup as if they are field values. They can be displayed in a table using the
 * [FieldInfo](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-FieldInfo.html) of the popupTemplate's content or referenced within a simple string.
 *
 * @since 4.11
 * @see [Arcade Popup Profile](https://developers.arcgis.com/javascript/latest/arcade/#popup)
 * @see [Arcade Feature Reduction Popup Profile](https://developers.arcgis.com/javascript/latest/arcade/#feature-reduction-popup)
 * @see [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html)
 * @see [Sample - Reference Arcade expressions in PopupTemplate](https://developers.arcgis.com/javascript/latest/sample-code/popuptemplate-arcade/)
 * @example
 * // Display a table in the popup's content referencing two values
 * // one from a field, and another returned from an Arcade expression
 * layer.popupTemplate = {
 *   title: "Population in {NAME}",
 *   content: [{
 *     type: "fields",
 *     fieldInfos: [{
 *       fieldName: "POP_2015",
 *       label: "Total population (2015)",
 *       format: {
 *         digitSeparator: true
 *       }
 *     }, {
 *       fieldName: "expression/per-asian"
 *     }]
 *   }]
 * };
 */
export default class ExpressionInfo extends JSONSupport {
  constructor(properties?: ExpressionInfoProperties);
  /**
   * An [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression following
   * the specification defined by the [Arcade Popup Profile](https://developers.arcgis.com/javascript/latest/arcade/#popup).
   * Expressions must return a string or a number and may access data values from the feature, its layer, or other layers
   * in the map or datastore with the `$feature`, `$layer`, `$map`, and `$datastore` profile variables.
   *
   * @see [Arcade Popup Profile](https://developers.arcgis.com/javascript/latest/arcade/#popup)
   * @see [Arcade Feature Reduction Popup Profile](https://developers.arcgis.com/javascript/latest/arcade/#feature-reduction-popup)
   * @example
   * // Calculates the percentage of the population that is Asian
   * expressionInfo.expression = "Text($feature.Asian / $feature.TOT_POP, '#.#%')";
   */
  accessor expression: string;
  /**
   * The name of the expression. This is used to reference the value of the
   * given `expression` in the popupTemplate's
   * [PopupTemplate.content](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html#content) property by wrapping
   * it in curly braces and prefacing it with `expression/`
   * (e.g. `{expression/expressionName}`).
   *
   * @example expressionInfo.name = "percent-asian";
   */
  accessor name: string;
  /** Indicates the return type of the Arcade expression. */
  accessor returnType: "string" | "number";
  /**
   * The title used to describe the value returned by the expression in the
   * popup. This will display if the value is referenced in a [FieldInfo](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-FieldInfo.html) table.
   *
   * @example expressionInfo.title = "Percent Asian";
   */
  accessor title: string | null | undefined;
  /**
   * Creates a deep clone of the ExpressionInfo class.
   *
   * @returns A deep clone of the ExpressionInfo instance.
   */
  clone(): ExpressionInfo;
}