import type FieldFormat from "./FieldFormat.js";

export interface DateTimeFieldFormatProperties extends Partial<Pick<DateTimeFieldFormat, "dateStyle" | "hour12" | "month" | "timeStyle" | "year">> {}

export type Hour12 = "always" | "auto" | "never";

/**
 * The `DateTimeFieldFormat` class defines the formatting options for date and time. It is used in the [FieldConfiguration](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-FieldConfiguration.html) class to define the display format of fields in a [FeatureLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-FeatureLayer.html). It applies to both the map's popup and any components/widgets that display the field. It is applicable to field [types](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-Field.html#type) of `date`, `date-only`, `time-only`, and `timestamp-offset`.
 *
 * > [!WARNING]
 * >
 * > **Breaking change**
 * > Some date formats may now appear slightly different. For example, if working with the `en-US` locale, the legacy [FieldInfoFormat.dateFormat](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-support-FieldInfoFormat.html#dateFormat) property would display `short-date` with a four-digit year, e.g. `3/4/2025`. Using `DateTimeFieldFormat` follows [CLDR](https://cldr.unicode.org/#what-is-cldr) standards based on the specified locale. For `en-US`, this means dates now display with a two-digit year, e.g. `3/4/25`.
 * > Set the [timeStyle](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-DateTimeFieldFormat.html#timeStyle) property to either `long` or `full` if the view’s [MapView.timeZone](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html#timeZone) is set to `unknown` and the field includes time information.
 *
 * ### Date/Time Format Mappings
 *
 * The following tables show equivalencies between the legacy [FieldInfoFormat.dateFormat](https://developers.arcgis.com/javascript/latest/api-reference/esri-popup-support-FieldInfoFormat.html#dateFormat) values and `DateTimeFieldFormat` properties. The examples shown are for the `en-US` locale. Note that the actual display will vary based on the locale of the user.
 *
 * > [!WARNING]
 * >
 * > **Breaking change**
 * > When using `dateStyle = "short"`, the display of the year varies by locale. For example, in the `en-US locale`, the year `1969` may be shown as `69`. This formatting follows the
 * > [CLDR](https://cldr.unicode.org/) standards.
 * ---
 *
 * #### Date & Time Formats
 *
 * | **Legacy FieldInfoFormat** | **Equivalent DateTimeFieldFormat** | **Example (en-US)** |
 * |---|---|---|
 * | `short-date` | `dateStyle = "short"` | 12/31/1969. |
 * | `short-date-short-time` | `dateStyle = "short"`, `timeStyle = "short"`, `hour12 = "always"` | 12/31/1969, 7:00 PM |
 * | `short-date-short-time-24` | `dateStyle = "short"`, `timeStyle = "short"`, `hour12 = never` | 12/31/1969, 19:00 |
 * | `short-date-long-time` | `dateStyle = "short"`, `timeStyle = "medium"`, `hour12 = "always"` | 12/31/1969, 7:00:00 PM |
 * | `short-date-long-time-24` | `dateStyle = "short"`, `timeStyle = "medium"`, `hour12 = never` | 12/31/1969, 19:00:00 |
 * | `long-month-day-year` | `dateStyle = "long"` | December 31, 1969 |
 * | `long-month-day-year-short-time` | `dateStyle = "long"`, `timeStyle = "short"`, `hour12 = "always"` | December 31, 1969, 7:00 PM |
 * | `long-month-day-year-short-time-24` | `dateStyle = "long"`, `timeStyle = "short"`, `hour12 = never` | December 31, 1969, 19:00 |
 * | `long-month-day-year-long-time` | `dateStyle = "long"`, `timeStyle = "medium"`, `hour12 = "always"` | December 31, 1969, 7:00:00 PM |
 * | `long-month-day-year-long-time-24` | `dateStyle = "long", timeStyle = "medium"`, `hour12 = never` | December 31, 1969, 19:00:00 |
 * | `day-short-month-year` | `dateStyle = "medium"` | Dec 31, 1969 |
 * | `day-short-month-year-short-time` | `dateStyle = "medium"`, `timeStyle = "short"`, `hour12 = "always"` | Dec 31, 1969, 7:00 PM |
 * | `day-short-month-year-short-time-24` | `dateStyle = "medium"`, `timeStyle = "short"`, `hour12 = never` | Dec 31, 1969, 19:00 |
 * | `day-short-month-year-long-time` | `dateStyle = "medium"`, `timeStyle = "medium"`, `hour12 = "always"` | Dec 31, 1969, 7:00:00 PM |
 * | `day-short-month-year-long-time-24` | `dateStyle = "medium"`, `timeStyle = "medium"`, `hour12 = never` | Dec 31, 1969, 19:00:00 |
 * | `long-date` | `dateStyle = "full"` | Wednesday, December 31, 1969 |
 * | `long-date-short-time` | `dateStyle = "full"`, `timeStyle = "short"`, `hour12 = "always"` | Wednesday, December 31, 1969, 7:00 PM |
 * | `long-date-short-time-24` | `dateStyle = "full"`, `timeStyle = "short"`, `hour12 = never` | Wednesday, December 31, 1969, 19:00 |
 * | `long-date-long-time` | `dateStyle = "full"`, `timeStyle = "medium"`, `hour12 = "always"` | Wednesday, December 31, 1969, 7:00:00 PM |
 * | `long-date-long-time-24` | `dateStyle = "full"`, `timeStyle = "medium"`, `hour12 = never` | Wednesday, December 31, 1969, 19:00:00 |
 *
 * ---
 *
 * #### Month/Year Only Formats
 *
 * | **Legacy (`Format.dateFormat`)** | **DateTimeFieldFormat equivalency** | **Example (en-US)** |
 * |---|---|---|
 * | `longMonthYear` | `month: "long"`, `year: "numeric"` | December 1969 |
 * | `shortMonthYear` | `month: "short"`, `year: "numeric"` | Dec 1969 |
 * | `year` | `year: "numeric"` | 1969 |
 *
 * ---
 *
 * #### Legacy (`LE`) Formats
 * | **Legacy (`Format.dateFormat`)** | **DateTimeFieldFormat equivalency** |
 * |---|---|
 * | `short-date-le`, `short-date-le-short-time`, `short-date-le-short-time-24`, `short-date-le-long-time`, `short-date-le-long-time-24` | Treated as equivalent to non-LE versions. `LE` is no longer needed since locale is implied from the browser. |
 *
 * @since 4.34
 * @see [MDN documentation - DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat)
 * @see [CLDR](https://cldr.unicode.org/)
 * @see [FieldConfiguration](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-FieldConfiguration.html)
 * @example
 * // Create a date-time field format
 * const dateTimeFormat = new DateTimeFieldFormat ({
 *   dateStyle: "medium",
 *   timeStyle: "short",
 *   hour12: "never"
 * });
 *
 * // Create a field configuration object containing the date-time format
 * const dateFieldConfiguration = new FieldConfiguration ({
 *   name: "pollsclose", // name of the field in the service
 *   fieldFormat: dateTimeFormat,
 *   alias: "Polls close"
 * });
 *
 * // Create a feature layer and pass in the field configurations
 * const featureLayer = new FeatureLayer ({
 *   url: "URL to feature service",
 *   outFields: ["*"],
 *   fieldConfigurations: [dateFieldConfiguration] // add as many field configurations as needed
 * });
 */
export default class DateTimeFieldFormat extends FieldFormat {
  constructor(properties?: DateTimeFieldFormatProperties);
  /**
   * Defines the date format. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#parameters).
   *
   * @since 4.34
   * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat)
   */
  accessor dateStyle: "full" | "long" | "medium" | "short" | null | undefined;
  /**
   * Determines whether to use 12-hour time (as opposed to 24-hour time). Possible values include:
   *
   * Value | Description
   * ------|------------
   *  always | Always use 12-hour time (e.g., 1 PM).
   *  auto | (_default_) Use either 12-hour or 24-hour time as based on the locale.
   *  never | Never use 12-hour time (e.g., 13:00).
   *
   * @default "auto"
   * @since 4.34
   * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#parameters)
   */
  accessor hour12: Hour12;
  /**
   * Specifies how the month is displayed. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat).
   *
   * @since 4.34
   * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat)
   */
  accessor month: "long" | "short" | null | undefined;
  /**
   * Defines the time format. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#parameters).
   *
   * @since 4.34
   * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat)
   */
  accessor timeStyle: "full" | "long" | "medium" | "short" | null | undefined;
  /**
   * The type of field format.
   *
   * @since 4.34
   */
  get type(): "date-time";
  /**
   * Specifies how the year is displayed. Currently, only supports `numeric`. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat).
   *
   * @since 4.34
   * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat)
   */
  accessor year: "numeric" | null | undefined;
}