import type Color from "../../Color.js";
import type ColorStop from "../../renderers/visualVariables/support/ColorStop.js";
import type { ColorLike } from "../../Color.js";
import type { ShadowCastTotalDurationMode } from "./types.js";
import type { Clonable } from "../../core/Clonable.js";
import type { ColorStopProperties } from "../../renderers/visualVariables/support/ColorStop.js";

/**
 * Properties that can be used to construct a [TotalDurationOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/) instance.
 *
 * @since 5.0
 */
export interface TotalDurationOptionsProperties extends Partial<Pick<TotalDurationOptions, "mode">> {
  /**
   * Defines the color used by the default color ramp for the visualization. The opacity is mapped to the time spent
   * in shadow. When [ShadowCastAnalysis.visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`, the opacity is mapped to the time
   * spent in sunlight instead. Areas that don't receive any shadow or sunlight are displayed with zero opacity and areas
   * that receive shadow or sunlight for the entire time range are displayed with the opacity specified in this color.
   *
   * When [colorStops](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/#colorStops) is not specified, the visualization uses a default ramp between transparent and this color. When specified, those stops are used instead.
   *
   * @default [0, 0, 255, 0.7]
   * @since 5.0
   */
  color?: ColorLike;
  /**
   * The color stops for the visualization.
   *
   * - Each stop defines a color and a duration value in milliseconds. The value represents shadow duration by default
   *   and sunlight duration when [ShadowCastAnalysis.visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`.
   * - In `continuous` mode, colors are interpolated between adjacent stops.
   * - In `hourly` mode, the displayed shadow or sunlight duration is snapped to the end of its hourly bucket before
   *   the color ramp is evaluated. For example, durations up to `1` hour use the `1`-hour ramp position, and in a
   *   `6`-hour analysis window, durations greater than `5` hours and up to `6` hours use the `6`-hour ramp position.
   * - If omitted, the visualization uses a default ramp between transparent and [color](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/#color). If specified, these stops are used.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > In a [3D SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/), a maximum of 8 color stops is supported.
   *
   * @since 5.1
   */
  colorStops?: ColorStopProperties[] | null;
}

/**
 * Configuration for the "total-duration" mode of the [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/).
 *
 * @since 5.0
 * @see [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/)
 * @see [ShadowCastAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/)
 * @see [Sample - Shadow Cast analysis](https://developers.arcgis.com/javascript/latest/sample-code/shadow-cast/)
 * @see [Shadow Cast component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/)
 */
export default class TotalDurationOptions extends Clonable {
  /** @since 5.0 */
  constructor(properties?: TotalDurationOptionsProperties);
  /**
   * Defines the color used by the default color ramp for the visualization. The opacity is mapped to the time spent
   * in shadow. When [ShadowCastAnalysis.visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`, the opacity is mapped to the time
   * spent in sunlight instead. Areas that don't receive any shadow or sunlight are displayed with zero opacity and areas
   * that receive shadow or sunlight for the entire time range are displayed with the opacity specified in this color.
   *
   * When [colorStops](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/#colorStops) is not specified, the visualization uses a default ramp between transparent and this color. When specified, those stops are used instead.
   *
   * @default [0, 0, 255, 0.7]
   * @since 5.0
   */
  get color(): Color;
  set color(value: ColorLike);
  /**
   * The color stops for the visualization.
   *
   * - Each stop defines a color and a duration value in milliseconds. The value represents shadow duration by default
   *   and sunlight duration when [ShadowCastAnalysis.visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`.
   * - In `continuous` mode, colors are interpolated between adjacent stops.
   * - In `hourly` mode, the displayed shadow or sunlight duration is snapped to the end of its hourly bucket before
   *   the color ramp is evaluated. For example, durations up to `1` hour use the `1`-hour ramp position, and in a
   *   `6`-hour analysis window, durations greater than `5` hours and up to `6` hours use the `6`-hour ramp position.
   * - If omitted, the visualization uses a default ramp between transparent and [color](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/#color). If specified, these stops are used.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > In a [3D SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/), a maximum of 8 color stops is supported.
   *
   * @since 5.1
   */
  get colorStops(): ColorStop[] | null | undefined;
  set colorStops(value: ColorStopProperties[] | null | undefined);
  /**
   * Determines how cumulative shadow or sunlight duration is visualized. Use `continuous` to display an interpolated
   * duration surface across the selected time range. Use `hourly` to snap values to hourly boundaries before applying
   * the color ramp at the end of each represented hour.
   *
   * @default "continuous"
   * @since 5.0
   */
  accessor mode: ShadowCastTotalDurationMode;
}