import type { ClonableMixin, ClonableMixinProperties } from "../../core/Clonable.js";
import type { JSONSupport, JSONSupportMixinProperties } from "../../core/JSONSupport.js";
import type { DateFormat } from "../../intl/date.js";

export interface FieldInfoFormatProperties extends JSONSupportMixinProperties, ClonableMixinProperties, Partial<Pick<FieldInfoFormat, "dateFormat" | "digitSeparator" | "places">> {}

/**
 * The `FieldInfoFormat` class is used with numerical or date fields to provide more detail
 * about how the value should be displayed in a popup. Use this class in place of the legacy
 * formatting functions: `DateString`, `DateFormat`, and/or `NumberFormat`.
 *
 * > [!WARNING]
 * >
 * > When formatting `Number` fields, you must set both the `digitSeparator` and `places`
 * > properties for the formatting to take effect.
 *
 * @since 4.11
 * @see [PopupTemplate](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html)
 * @see [FieldInfo](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-FieldInfo.html)
 * @see [intl](https://developers.arcgis.com/javascript/latest/api-reference/esri-intl.html)
 * @see [Sample - Intro to PopupTemplate](https://developers.arcgis.com/javascript/latest/sample-code/intro-popuptemplate/)
 * @see [Sample - Custom popup actions per feature](https://developers.arcgis.com/javascript/latest/sample-code/popup-custom-action/)
 * @see [Sample - Multiple popup elements](https://developers.arcgis.com/javascript/latest/sample-code/popup-multipleelements/)
 * @see [Sample - PopupTemplate function](https://developers.arcgis.com/javascript/latest/sample-code/popuptemplate-function/)
 * @see [Sample - PopupTemplate with promise](https://developers.arcgis.com/javascript/latest/sample-code/popuptemplate-promise/)
 * @example
 * let fieldInfo = new FieldInfo({
 *   fieldName: "PROMINENCE_ft",
 *   label: "Prominence (feet)",
 *   //autocasts to FieldInfo.Format
 *   format: {
 *     places: 0,
 *     digitSeparator: true
 *   }
 * };
 */
export default class FieldInfoFormat extends FieldInfoFormatSuperclass {
  constructor(properties?: FieldInfoFormatProperties);
  /**
   * Used only with `Date` fields. Specifies how the date should appear in a popup.
   *
   * **Possible Values**
   *
   * | **Format** | **Date Formatting** |
   * |---|---|
   * | **short-date** | 12/31/1969   |
   * | **short-date-short-time** | 12/31/1969, 7:00 PM |
   * | **short-date-short-time-24** | 12/31/1969, 19:00 |
   * | **short-date-long-time** | 12/31/1969, 7:00:00 PM |
   * | **short-date-long-time-24** | 12/31/1969, 19:00:00 |
   * | **long-month-day-year** | December 31, 1969 |
   * | **long-month-day-year-short-time** | December 31, 1969, 7:00 PM |
   * | **long-month-day-year-short-time-24** | December 31, 1969, 19:00 |
   * | **long-month-day-year-long-time** | December 31, 1969, 7:00:00 PM |
   * | **long-month-day-year-long-time-24** | December 31, 1969, 19:00:00 |
   * | **day-short-month-year** | Dec 31, 1969 |
   * | **day-short-month-year-short-time** | Dec 31, 1969, 7:00 PM |
   * | **day-short-month-year-short-time-24** | Dec 31, 1969, 19:00 |
   * | **day-short-month-year-long-time** | Dec 31, 1969, 7:00:00 PM |
   * | **day-short-month-year-long-time-24** | Dec 31, 1969, 19:00:00 |
   * | **long-date** | Wednesday, December 31, 1969 |
   * | **long-date-short-time** | Wednesday, December 31, 1969, 7:00 PM |
   * | **long-date-short-time-24** | Wednesday, December 31, 1969, 19:00 |
   * | **long-date-long-time** | Wednesday, December 31, 1969, 7:00:00 PM |
   * | **long-date-long-time-24** | Wednesday, December 31, 1969, 19:00:00 |
   * | **long-month-year** | December 1969 |
   * | **short-month-year** | Dec 1969 |
   * | **year** | 1969 |
   *
   * > [!WARNING]
   * >
   * > The `time-only` date fields will only honor the _time_ component (i.e. _ShortTime_, _ShortTime24_,
   * > _LongTime_ or _LongTime24_) in a dateFormat. Date formats without a time component are not supported by time-only fields.
   * > Starting with version 4.28, `date` fields are formatted using the `short-date-short-time` format rather than
   * > `long-month-day-year` in [popup templates](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html) created with the [createPopupTemplate()](https://developers.arcgis.com/javascript/latest/api-reference/esri-support-popupUtils.html#createPopupTemplate) method.
   * > This is also the case for default [popup templates](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html) created by setting the `defaultPopupTemplateEnabled` property to `true` on the
   * > [Popup#defaultPopupTemplateEnabled](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Popup.html#defaultPopupTemplateEnabled), [Features](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Features-FeaturesViewModel.html#defaultPopupTemplateEnabled), or [Feature#defaultPopupTemplateEnabled](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Feature.html#defaultPopupTemplateEnabled) widgets.
   * > For example, previously a date that may have appeared as `"December 30, 1997"` will now appear as `"12/30/1997 6:00 PM"`.
   * > fields that need to have number formatting for chart/text elements.
   * > If displaying a `timestamp-offset` or `date` [Field#type](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-Field.html#type) field in a [Popup](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Popup.html), [Features](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Features.html), or [Feature](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Feature.html) widget and the [MapView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html) has a [MapView#timeZone](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html#timeZone) set other than `unknown`,
   * > the abbreviated time zone suffix will be omitted from the attribute value. For example, the attribute value will display as `9/28/2014, 7:58 PM`. To display an abbreviated time zone suffix, see the `Read more` section.
   * > <details>
   * > <summary>Read More</summary>
   * >
   * >   * If the user wants `date` fields to show a time zone suffix (e.g. `9/28/2014, 7:58 PM PST`), then the [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) [Text](https://developers.arcgis.com/arcade/function-reference/text_functions/#text) function can be used to format the field value. This can be done either with [ExpressionContent](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-content-ExpressionContent.html) or [attribute expressions](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-ExpressionInfo.html).
   * >     ```js
   * >     // Attribute expression using expressionInfos to append the time zone suffix to a date field.
   * >     // Date field types will show in the MapView's current time zone.
   * >     layer.popupTemplate = {
   * >       title: "Display time zones",
   * >       fieldInfos: [{
   * >         fieldName: "expression/date-with-time-zone-suffix",
   * >       }],
   * >       expressionInfos: [{
   * >         expression: `Text($feature.date_Field, "M/D/Y, h:mm A ZZZZ")`,
   * >         name: "date-with-time-zone-suffix",
   * >       }],
   * >       content: [{
   * >         type: "fields"
   * >       }]
   * >     };
   * >     ```
   * >     ```js
   * >     // ExpressionContent to append the time zone suffix to a date field.
   * >     // Date field types will show in the MapView's current time zone by default.
   * >     layer.popupTemplate = {
   * >       title: "Display time zones",
   * >       content: [{
   * >         type: "expression",
   * >         expressionInfo: {
   * >           expression: `return {
   * >             type : 'text',
   * >             text : Text($feature.date_Field, "M/D/Y, h:mm A ZZZZ")
   * >           }`
   * >         }
   * >       }]
   * >      };
   * >     ```
   * >   * If the user wants `timestamp-offset` fields to display in the time zone from the server with an abbreviated time zone suffix, then the [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) [Text](https://developers.arcgis.com/arcade/function-reference/text_functions/#text) function can be used to format the field value. This can be done either with [ExpressionContent](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-content-ExpressionContent.html) or [attribute expressions](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-ExpressionInfo.html).
   * >     ```js
   * >     // Attribute expression using expressionInfos to append the time zone suffix to a timestamp-offset field.
   * >     layer.popupTemplate = {
   * >       title: "Display time zones",
   * >       fieldInfos: [{
   * >         fieldName: "expression/TSO-from-server",
   * >       }],
   * >       expressionInfos: [{
   * >         expression: `Text($feature.TimestampOffset_Field, "M/D/Y, h:mm A ZZZZ")`,
   * >         name: "TSO-from-server",
   * >       }],
   * >       content: [{
   * >         type: "fields"
   * >       }]
   * >     };
   * >     ```
   * >     ```js
   * >     // ExpressionContent to append the time zone suffix to a timestamp-offset field.
   * >     layer.popupTemplate = {
   * >       title: "Display time zones",
   * >       content: [{
   * >         type: "expression",
   * >         expressionInfo: {
   * >           expression: `return {
   * >             type : 'text',
   * >             text : Text($feature.TimestampOffset_Field, "M/D/Y, h:mm A ZZZZ")
   * >           }`
   * >         }
   * >       }]
   * >      };
   * >     ```
   * >   * If the user wants `timestamp-offset` fields to display in the MapView's time zone with an abbreviated time zone suffix, then the [`ChangeTimeZone`](https://developers.arcgis.com/javascript/latest/arcade/function-reference/date_functions/#changetimezone) [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) function can be used to format the value.
   * >     ```js
   * >     // Attribute expression using expressionInfos to append the MapView's current time zone suffix to a timestamp-offset field
   * >     layer.popupTemplate = {
   * >       title: "Display time zones",
   * >       fieldInfos: [{
   * >         fieldName: "expression/TSO-matching-view-tz",
   * >       }],
   * >       expressionInfos: [{
   * >         expression: `Text(ChangeTimeZone($feature.TimestampOffset_Field, GetEnvironment().timeZone), "M/D/Y, h:mm A ZZZZ")`,
   * >         name: "TSO-matching-view-tz",
   * >       }],
   * >       content: [{
   * >         type: "fields"
   * >       }]
   * >     };
   * >     ```
   * >     ```js
   * >     // ExpressionContent to append the MapView's current time zone suffix to a timestamp-offset field
   * >     layer.popupTemplate = {
   * >       title: "Display time zones",
   * >       content: [{
   * >         type: "expression",
   * >         expressionInfo: {
   * >           expression: `return {
   * >             type: "text",
   * >             text: Text(ChangeTimeZone($feature.TimestampOffset_Field, GetEnvironment().timeZone), "M/D/Y, h:mm A ZZZZ")
   * >           }`
   * >         }
   * >       }]
   * >     };
   * >     ```
   * >
   * > </details>
   *
   * @see [intl](https://developers.arcgis.com/javascript/latest/api-reference/esri-intl.html)
   * @see [ElementExpressionInfo](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-ElementExpressionInfo.html)
   */
  dateFormat?: DateFormat | null;
  /**
   * Used only with `Number` fields. A value of `true` indicates the number
   * should have a digit (or thousands) separator when the value appears in popups.
   * A value of `false` means that no separator will be used.
   *
   * @default false
   */
  accessor digitSeparator: boolean;
  /**
   * Used only with `Number` fields to specify the number of supported decimal places
   * that should appear in popups. Any places beyond this value are rounded.
   */
  accessor places: number | null | undefined;
}
declare const FieldInfoFormatSuperclass: typeof JSONSupport & typeof ClonableMixin