/** A module for importing types used in the [TimeSlider](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/) widget and [TimeSliderViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/TimeSliderViewModel/). */
import type TimeExtent from "../../time/TimeExtent.js";
import type TimeInterval from "../../time/TimeInterval.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";

/**
 * The [TimeSliderViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/TimeSliderViewModel/)'s state.
 *
 * @since 5.0
 */
export type TimeSliderState = "disabled" | "ready" | "playing";

/**
 * The time slider mode.
 *
 * @see [TimeSlider.mode](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#mode)
 * @since 5.0
 */
export type TimeSliderMode = "instant" | "time-window" | "cumulative-from-start" | "cumulative-from-end";

/**
 * Specifies an array of dates for the time slider widget. Can be used to create irregularly spaced stops.
 *
 * @since 5.0
 * @example
 * // Explicitly define 5 stops.
 * const timeSlider = new TimeSlider({
 *   container: "timeSliderDiv",
 *   fullTimeExtent: {
 *     start: new Date(2000, 0, 1),
 *     end: new Date(2004, 2, 19)
 *   },
 *   timeExtent: {
 *     start: new Date(2000, 0, 1),
 *     end: new Date(2001, 3, 8)
 *   },
 *   stops: {
 *     dates: [
 *       new Date(2000, 0, 1),
 *       new Date(2001, 3, 8),
 *       new Date(2002, 0, 10),
 *       new Date(2003, 12, 8),
 *       new Date(2004, 2, 19)
 *     ]
 *   }
 * });
 */
export interface StopsByDates {
  /**
   * Array of dates.
   *
   * @since 5.0
   */
  dates: Date[];
}

/**
 * Defines regularly spaced stops on the time slider from a [TimeInterval](https://developers.arcgis.com/javascript/latest/references/core/time/TimeInterval/). The optional
 * [TimeExtent](https://developers.arcgis.com/javascript/latest/references/core/time/TimeExtent/) can confine the subdivision to a specific time frame. StopByInterval is useful
 * when the spacing is in terms of months and years, which cannot be reliably expressed in milliseconds.
 *
 * @since 5.0
 * @example
 * // Add yearly intervals starting from the beginning of the TimeSlider.
 * const timeSlider = new TimeSlider({
 *   container: "timeSliderDiv",
 *   fullTimeExtent: {
 *     start: new Date(2000, 0, 1),
 *     end: new Date(2015, 2, 19)
 *   },
 *   timeExtent: {
 *     start: new Date(2000, 0, 1),
 *     end: new Date(2001, 0, 1)
 *   },
 *   stops: {
 *     interval: {
 *       value: 1,
 *       unit: "years"
 *     }
 *   }
 * });
 */
export interface StopsByInterval {
  /**
   * Specifies a granularity of temporal data and allows you to visualize the data at specified intervals. It can be set at regular interval such as every hour or every day.
   *
   * @since 5.0
   */
  interval: TimeInterval;
  /**
   * A period of time with definitive start and end dates. The time slider widget's [TimeSlider.fullTimeExtent](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#fullTimeExtent) will be used if this property is not specified.
   *
   * @since 5.0
   */
  timeExtent?: TimeExtent;
}

/**
 * Divides the time slider's [TimeSlider.fullTimeExtent](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#fullTimeExtent) into equal parts.
 * A stop will be placed at the start and end of each division resulting in _count + 1_ [TimeSlider.effectiveStops](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#effectiveStops).
 *
 * @since 5.0
 * @example
 * // Add ten evenly spaced stops.
 * const timeSlider = new TimeSlider({
 *   container: "timeSliderDiv",
 *   fullTimeExtent: {
 *     start: new Date(2000, 0, 1),
 *     end: new Date(2004, 2, 19)
 *   },
 *   timeExtent: {
 *     start: new Date(2000, 0, 1),
 *     end: new Date(2000, 3, 8)
 *   },
 *   stops: {
 *     count: 10
 *   }
 * });
 */
export interface StopsByCount {
  /**
   * Number of evenly spaced divisions.
   *
   * @since 5.0
   */
  count: number;
  /**
   * The time period to divide. If unspecified, the time slider's [TimeSlider.fullTimeExtent](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#fullTimeExtent) will be used.
   *
   * @since 5.0
   */
  timeExtent?: TimeExtent;
}

/**
 * Defines specific locations on the time slider where thumbs will snap to when manipulated. If unspecified, ten evenly spaced stops will be added.
 * For continuous sliding set stops to `null`.
 *
 * @see [TimeSlider.stops](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#stops)
 * @since 5.0
 */
export type Stops = StopsByDates | StopsByInterval | StopsByCount;

/**
 * Definition of an action that can be assigned to the [TimeSliderViewModel.actions](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/TimeSliderViewModel/#actions) property on the
 * [TimeSlider.actions](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#actions) or the [TimeSliderViewModel.actions](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/TimeSliderViewModel/#actions). It is displayed in a menu when
 * the user clicks the ellipsis button ![timeSlider-actions-menu](https://developers.arcgis.com/javascript/latest/assets/img/apiref/widgets/timeslider/ellipsis.png) on the [TimeSlider](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/) widget.
 *
 * @since 5.0
 */
export interface Action {
  /**
   * Unique identifier of the action.
   *
   * @since 5.0
   */
  id: string;
  /**
   * The name of the icon to display. The value of this property must match the icon name
   *                            from [Calcite UI Icons](https://developers.arcgis.com/calcite-design-system/icons/).
   *
   * @since 5.0
   */
  icon: Icon["icon"];
  /**
   * The title of the action that will be displayed in the menu.
   *
   * @since 5.0
   */
  title: string;
}

/**
 * Settings derived from a [time slider widget](https://developers.arcgis.com/javascript/latest/references/core/webdoc/Widgets/#timeSlider) in a [web map](https://developers.arcgis.com/javascript/latest/references/core/WebMap/).
 *
 * @since 5.0
 */
export interface TimeSliderSettings {
  /**
   * The temporal extent of the entire slider.
   *
   * @since 5.0
   * @see [TimeSlider.fullTimeExtent](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#fullTimeExtent)
   */
  fullTimeExtent?: TimeExtent | null;
  /**
   * When `true`, the time slider will play its animation in a loop.
   *
   * @since 5.0
   * @see [TimeSlider.loop](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#loop)
   */
  loop: boolean;
  /**
   * The time slider mode.
   *
   * @since 5.0
   * @see [TimeSlider.mode](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#mode)
   */
  mode: TimeSliderMode;
  /**
   * The time (in milliseconds) between animation steps.
   *
   * @since 5.0
   * @see [TimeSlider.playRate](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#playRate)
   */
  playRate: number;
  /**
   * Defines specific locations on the time slider where thumbs will snap to when manipulated.
   *
   * @since 5.0
   * @see [TimeSlider.stops](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#stops)
   */
  stops?: Stops | null;
  /**
   * The current time extent of the time slider.
   *
   * @since 5.0
   * @see [TimeSlider.timeExtent](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/#timeExtent)
   */
  timeExtent?: TimeExtent | null;
}