import type Analysis from "./Analysis.js";
import type DiscreteOptions from "./ShadowCast/DiscreteOptions.js";
import type MinDurationOptions from "./ShadowCast/MinDurationOptions.js";
import type TotalDurationOptions from "./ShadowCast/TotalDurationOptions.js";
import type Polygon from "../geometry/Polygon.js";
import type { AnalysisProperties } from "./Analysis.js";
import type { DiscreteOptionsProperties } from "./ShadowCast/DiscreteOptions.js";
import type { MinDurationOptionsProperties } from "./ShadowCast/MinDurationOptions.js";
import type { TotalDurationOptionsProperties } from "./ShadowCast/TotalDurationOptions.js";
import type { ShadowCastMode } from "./ShadowCast/types.js";
import type { PolygonProperties } from "../geometry/Polygon.js";

/**
 * Properties that can be used to construct a [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/) instance.
 *
 * @since 5.0
 */
export interface ShadowCastAnalysisProperties extends AnalysisProperties, Partial<Pick<ShadowCastAnalysis, "endTimeOfDay" | "mode" | "startTimeOfDay" | "utcOffset" | "visualizeSunlight">> {
  /**
   * The calendar date used to calculate the shadow cast. This date excludes the time.
   * If a date with a time is set, the time value will be set to midnight (`00:00:00`) of that date in local system time.
   * If no date is set, then it defaults to the current date in local system time.
   *
   * @since 5.0
   */
  date?: (Date | number | string);
  /**
   * Options specific to the `discrete` mode.
   *
   * @since 5.0
   */
  discreteOptions?: DiscreteOptionsProperties;
  /**
   * Polygonal area inside which to apply the shadow cast analysis. Use this property to limit the visualization to a
   * project area, such as a parcel, park, or courtyard. If not set, the analysis applies to the entire scene.
   *
   * @since 5.1
   */
  geometry?: PolygonProperties | null;
  /**
   * Options specific to the `min-duration` mode.
   *
   * @since 5.0
   */
  minDurationOptions?: MinDurationOptionsProperties;
  /**
   * Options specific to the `total-duration` mode.
   *
   * @since 5.0
   */
  totalDurationOptions?: TotalDurationOptionsProperties;
}

/**
 * The ShadowCastAnalysis visualizes shadows cast by 3D features or sunlight exposure in a
 * [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). This type of analysis is helpful in urban development, where projects may need to satisfy
 * shadow or sunlight exposure requirements for a selected day and time range.
 *
 * [![total duration mode](https://developers.arcgis.com/javascript/latest/assets/references/core/analysis/shadow-cast-analysis-duration.avif)](https://developers.arcgis.com/javascript/latest/sample-code/shadow-cast/)
 *
 * By default, the analysis visualizes shadows. When [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`,
 * it visualizes sunlight exposure instead.
 *
 * The [date](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#date), [startTimeOfDay](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#startTimeOfDay),
 * [endTimeOfDay](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#endTimeOfDay), and [utcOffset](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#utcOffset) properties define
 * the date, time range, and UTC offset used to compute the analysis overlay. They do not change the lighting in the
 * scene. To control scene lighting, use [SunLighting](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/) or the
 * [Daylight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/)
 * component.
 *
 * The [utcOffset](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#utcOffset) property determines which timezone the selected date and time range
 * are interpreted in for the analysis. This differs from the Daylight component, where selecting a timezone updates the
 * [environment lighting's](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment)
 * date and time according to the camera position.
 *
 * When set, the [geometry](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#geometry) property limits the visualization to a polygonal project
 * area, such as a parcel, park, or courtyard. If no geometry is provided, the analysis applies to the entire scene.
 * For `total-duration` and `discrete` visualizations, the [TotalDurationOptions.colorStops](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/#colorStops) or
 * [DiscreteOptions.colorStops](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/DiscreteOptions/#colorStops) properties define a custom color ramp. In `total-duration`
 * mode, stops define duration values. In `discrete` mode, stops define sample-count values. If color stops are not
 * provided, the visualization uses a default transparent-to-color ramp.
 *
 * The [mode](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#mode) property controls how shadow or sunlight exposure is visualized:
 *
 * | Mode | Use for | Details |
 * | --- | --- | --- |
 * | `min-duration` | Highlighting areas that meet or exceed a minimum shadow or sunlight duration. | The threshold is defined by [MinDurationOptions.minDuration](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/MinDurationOptions/#minDuration). |
 * | `total-duration` | Showing cumulative shadow or sunlight duration across the analysis area. | Supports continuous visualization or 1-hour intervals. In hourly mode, each bucket uses the color at the end of the represented hour. Without color stops, areas with no duration remain transparent, intermediate values are interpolated, and the highest duration uses the opacity from [TotalDurationOptions.color](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/#color). |
 * | `discrete` | Displaying individual shadow or sunlight samples at regular intervals. | The interval is defined by [DiscreteOptions.interval](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/DiscreteOptions/#interval). For example, a one-hour range with a 30-minute interval displays samples at the start, middle, and end of the range. |
 *
 * By default, the analysis also displays a tooltip next to the pointer. In continuous `total-duration` and
 * `min-duration` modes, the tooltip reports the total duration at that location, rounded to 15-minute increments. In
 * hourly `total-duration` mode, the tooltip reports the hourly range represented by the displayed bucket. In
 * `discrete` mode, the tooltip reports the duration at that location. The tooltip reports shadow duration by default
 * and sunlight duration when [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`.
 *
 * To perform a shadow cast analysis in your [WebScene](https://developers.arcgis.com/javascript/latest/references/core/WebScene/):
 * - Create a new instance of ShadowCastAnalysis.
 * - Set the desired [mode](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#mode).
 * - Configure the analysis time range using the [date](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#date), [startTimeOfDay](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#startTimeOfDay),
 * and [endTimeOfDay](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#endTimeOfDay) properties.
 * - Optionally set [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) to visualize sunlight duration instead of shadow duration.
 * - Optionally set [geometry](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#geometry) to limit the analysis to a polygonal project area.
 * - Optionally set the [utcOffset](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#utcOffset) property to define the timezone used for the analysis.
 * - If using the `discrete` [mode](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#mode), optionally set custom properties with [DiscreteOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/DiscreteOptions/).
 * - If using the `min-duration` [mode](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#mode), optionally set custom properties with [MinDurationOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/MinDurationOptions/).
 * - If using the `total-duration` [mode](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#mode), optionally set custom properties with [TotalDurationOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/).
 * - Add the ShadowCastAnalysis instance to [SceneView.analyses](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#analyses).
 *
 * ```js
 * const projectArea = new Polygon({
 *   rings: [
 *     [
 *       [-122.421, 37.781],
 *       [-122.42, 37.781],
 *       [-122.42, 37.782],
 *       // ...
 *     ]
 *   ]
 * });
 *
 * const analysis = new ShadowCastAnalysis({
 *   date: new Date("March 1, 2026"),
 *   startTimeOfDay: 10 * 3600 * 1000, // 10AM
 *   endTimeOfDay: 16 * 3600 * 1000, // 4PM
 *   mode: "total-duration",
 *   visualizeSunlight: true,
 *   geometry: projectArea,
 *   totalDurationOptions: {
 *     mode: "continuous",
 *     colorStops: [
 *       // Map sunlight duration to colors. Values are in milliseconds.
 *       { value: 0, color: [255, 255, 255, 0] },
 *       { value: 2 * 3600 * 1000, color: [255, 198, 87, 0.5] },
 *       { value: 4 * 3600 * 1000, color: [84, 176, 74, 0.85] }
 *     ]
 *   },
 *   utcOffset: -8 // Pacific Standard Time
 * });
 *
 * view.analyses.add(analysis);
 * ```
 *
 * Use the [ShadowCastAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/) class and its
 * [ShadowCastAnalysisView3D.getDurationAtScreen()](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/#getDurationAtScreen) method to
 * obtain the shadow or sunlight duration at a specific screen location programmatically.
 * To disable the shadow or sunlight tooltip next to the pointer set the [ShadowCastAnalysisView3D.interactive](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/#interactive)
 * property to `false`.
 *
 * ```js
 * // use getDurationAtScreen method from the analysis view once available
 * const analysisView = await view.whenAnalysisView(analysis);
 *
 * view.on("pointer-move", async (event) => {
 *   // duration is the sunlight duration in milliseconds because visualizeSunlight is true.
 *   // A negative duration means the pointer is outside the project area.
 *   const duration = await analysisView.getDurationAtScreen({ x: event.x, y: event.y });
 *   // ... do something with the duration
 * });
 * ```
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > - Terrain does not cast shadows in this analysis.
 * > - As a result, shadow duration may be underestimated and sunlight duration may be overestimated in areas where
 * > terrain would normally block sunlight. To avoid incorrect visualization, `startTimeOfDay` should be set after local
 * > sunrise and `endTimeOfDay` before local sunset.
 * > - The analysis does not take daylight savings into account. Use the timezone dropdown to adjust the offset from
 * > the Coordinated Universal Time (UTC) and account for the daylight
 * > saving time.
 * > - The timezone is automatically detected based on the camera location. In some situations this might
 * > not be accurate. In case of an inaccurate timezone, users can set it manually using the [utcOffset](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#utcOffset).
 *
 * @since 5.0
 * @see [ShadowCastAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/)
 * @see [DiscreteOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/DiscreteOptions/)
 * @see [TotalDurationOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/TotalDurationOptions/)
 * @see [MinDurationOptions](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCast/MinDurationOptions/)
 * @see [SunLighting](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/)
 * @see [Sample - Shadow Cast analysis object](https://developers.arcgis.com/javascript/latest/sample-code/analysis-shadow-cast/)
 * @see [Sample - Sunlight analysis](https://developers.arcgis.com/javascript/latest/sample-code/analysis-sunlight/)
 * @see [Sample - Analysis objects](https://developers.arcgis.com/javascript/latest/sample-code/analysis-objects/)
 * @see [Shadow Cast component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/)
 */
export default class ShadowCastAnalysis extends Analysis {
  /** @since 5.0 */
  constructor(properties?: ShadowCastAnalysisProperties);
  /**
   * The calendar date used to calculate the shadow cast. This date excludes the time.
   * If a date with a time is set, the time value will be set to midnight (`00:00:00`) of that date in local system time.
   * If no date is set, then it defaults to the current date in local system time.
   *
   * @since 5.0
   */
  get date(): Date;
  set date(value: (Date | number | string));
  /**
   * Options specific to the `discrete` mode.
   *
   * @since 5.0
   */
  get discreteOptions(): DiscreteOptions;
  set discreteOptions(value: DiscreteOptionsProperties);
  /**
   * Time (in milliseconds from midnight of the [date](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#date)) when the shadow cast computation should stop.
   * By default the shadow cast end time is set to 4PM (16 * 3600 * 1000ms).
   *
   * @default 57_600_000
   * @since 5.0
   */
  accessor endTimeOfDay: number;
  /**
   * Polygonal area inside which to apply the shadow cast analysis. Use this property to limit the visualization to a
   * project area, such as a parcel, park, or courtyard. If not set, the analysis applies to the entire scene.
   *
   * @since 5.1
   */
  get geometry(): Polygon | null | undefined;
  set geometry(value: PolygonProperties | null | undefined);
  /**
   * Options specific to the `min-duration` mode.
   *
   * @since 5.0
   */
  get minDurationOptions(): MinDurationOptions;
  set minDurationOptions(value: MinDurationOptionsProperties);
  /**
   * Mode of analysis to use when computing and displaying shadows or sunlight.
   *
   * - `"discrete"`: Displays individual shadow or sunlight snapshots at regular time intervals within the selected time range.
   * - `"min-duration"`: Displays areas where accumulated shadow or sunlight exceeds a user-defined minimum duration within the selected time range. Optional discrete shadow overlays can provide additional context when visualizing shadows.
   * - `"total-duration"`: Displays total shadow or sunlight accumulation within the selected time range. Supports
   *   continuous or 1-hour aggregated modes, where hourly buckets use the color at the end of the represented hour.
   *
   * When [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight) is `true`, the selected mode displays sunlight duration
   * instead of shadow duration.
   *
   * @default "min-duration"
   * @since 5.0
   */
  accessor mode: ShadowCastMode;
  /**
   * Time (in milliseconds from midnight of the [date](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#date)) when the shadow cast computation should start.
   * By default the shadow cast start time is set to 10AM (10 * 3600 * 1000ms).
   *
   * @default 36_000_000
   * @since 5.0
   */
  accessor startTimeOfDay: number;
  /**
   * Options specific to the `total-duration` mode.
   *
   * @since 5.0
   */
  get totalDurationOptions(): TotalDurationOptions;
  set totalDurationOptions(value: TotalDurationOptionsProperties);
  /**
   * The analysis type.
   *
   * @since 5.0
   */
  get type(): "shadow-cast";
  /**
   * The UTC offset in hours (e.g., `-8` for PST, `1` for CET). This value determines how the [date](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#date),
   * [startTimeOfDay](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#startTimeOfDay), and [endTimeOfDay](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#endTimeOfDay) properties are interpreted when computing the
   * shadow cast analysis.
   *
   * If not specified, the analysis will automatically determine an approximate UTC offset based on the longitude of the
   * view's camera position.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > Full support for time zones with daylight saving time is not yet supported.
   *
   * @since 5.0
   */
  accessor utcOffset: number | null | undefined;
  /**
   * Indicates whether the analysis is ready to be computed and interacted with in the view.
   *
   * @since 5.0
   */
  get valid(): boolean;
  /**
   * When `true`, the analysis visualizes sunlight duration instead of shadow duration. This applies to all modes,
   * their respective options, and the duration reported by
   * [ShadowCastAnalysisView3D.getDurationAtScreen()](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/#getDurationAtScreen).
   *
   * @default false
   * @since 5.1
   */
  accessor visualizeSunlight: boolean;
}