@arcgis/map-components 5.2.0-next.11 → 5.2.0-next.111

package/dist/components/arcgis-daylight/customElement.d.ts

@@ -22,6 +22,22 @@ import type { Icon as Icon } from "@esri/calcite-components/components/calcite-i
  * [date](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/#date) property of
  * [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment).
  *
+ * **How date, time, and timezone work**
+ *
+ * In sunlight mode, `SunLighting.date` is the source of truth for the scene lighting instant. The daylight component's
+ * `utcOffset` controls how that instant is displayed (date and slider time) and how user-entered local values are
+ * converted back to UTC.
+ *
+ * This means changing only [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#utcOffset) updates the displayed local date/time but
+ * preserves the same lighting instant. Changing [localDate](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#localDate) and/or
+ * [timeSliderPosition](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#timeSliderPosition) writes a new `SunLighting.date` instant.
+ *
+ * > [!IMPORTANT]
+ * >
+ * > Daylight does not use [arcgis-scene.timeZone](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#timeZone). Changing the scene's time zone does not update the
+ * > date and time shown in Daylight or change the lighting instant. Support for using the scene's time zone is planned
+ * > for a future release.
+ *
  * [![daylight-default](https://developers.arcgis.com/javascript/latest/assets/references/core/components/daylight/daylight-default.avif)](https://developers.arcgis.com/javascript/latest/sample-code/daylight/)
  *
  * The component has an option to select the timezone. When the user makes any adjustments here, a new time
@@ -54,14 +70,14 @@ import type { Icon as Icon } from "@esri/calcite-components/components/calcite-i
  * **Things to consider**
  *
  * * Daylight is only supported in a 3D [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/) component.
- * * The Daylight component uses UTC time and does not account for the daylight savings times in different countries and regions of the world.
+ * * The Daylight component uses a numeric UTC offset and does not track an IANA time zone. It does not account for daylight saving time transitions in different countries and regions.
  * * When using the [virtual light](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/VirtualLighting/),
  * setting the time and date programmatically does not have an influence on the lighting conditions of the scene.
  * * When using the [sunlight](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/),
  * the time slider and time zone automatically react to the changes of the camera (e.g., position, rotation, pan, zoom) because the position of the simulated sun
  * is updated to maintain a consistent solar time of day based on the camera's current longitude. This can be adjusted using the
  * [cameraTrackingEnabled](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/#cameraTrackingEnabled)
- * property on [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment).
+ * property on [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment). This camera-based timezone behavior is an approximation based on longitude.
  *
  * @see [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment)
  * @see [SunLighting](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/)
@@ -78,6 +94,15 @@ export abstract class ArcgisDaylight extends LitElement {
    * prevent memory leaks.
    *
    * @default false
+   * @example
+   * ```html
+   * <arcgis-daylight auto-destroy-disabled></arcgis-daylight>
+   * ```
+   *
+   * ```js
+   * daylightElement.autoDestroyDisabled = true;
+   * ```
+   * 
    */
   accessor autoDestroyDisabled: boolean;
   /**
@@ -88,7 +113,7 @@ export abstract class ArcgisDaylight extends LitElement {
    */
   accessor currentSeason: Season;
   /**
-   * Controls whether the component displays a date or a season picker. When the date picker is set, the user selects the date from a calendar. The season picker allows the user to choose a season from a drop-down list. Each season uses a fixed date corresponding to the equinoxes and solstices of 2014.
+   * Controls whether the component displays a date or a season picker. When the date picker is set, the user selects the date from a calendar. The season picker allows the user to choose a season from a drop-down list. Each season uses a fixed month and day corresponding to the equinoxes and solstices in the current local date's year.
    *
    * @default "date"
    */
@@ -97,6 +122,9 @@ export abstract class ArcgisDaylight extends LitElement {
    * Starts or pauses the daytime animation cycling through the minutes of the day.
    * Set the property to `true` to start the animation and to `false` to pause it.
    *
+   * `dayPlaying` and [yearPlaying](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#yearPlaying) are mutually exclusive.
+   * When virtual lighting is active, playback is stopped.
+   *
    * @default false
    */
   accessor dayPlaying: boolean;
@@ -130,6 +158,9 @@ export abstract class ArcgisDaylight extends LitElement {
   /**
    * The calendar date in the timezone given by [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#utcOffset).
    *
+   * Date-only ISO strings in `YYYY-MM-DD` format are preserved as-is to avoid day shifts in negative local
+   * timezones. Other valid `Date`, `number`, and `string` values are normalized to canonical `YYYY-MM-DD`.
+   *
    * @example
    * ```js
    * daylight.localDate = new Date("2005-08-25");
@@ -214,7 +245,7 @@ export abstract class ArcgisDaylight extends LitElement {
   /**
    * Slider position for the time of day in the timezone
    * given by [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#utcOffset). The position represents the time
-   * of the day in minutes. Possible values range between 0 and 1440.
+   * of the day in minutes. Values are normalized to a single day (0-1439).
    *
    * @example
    * ```js
@@ -243,15 +274,35 @@ export abstract class ArcgisDaylight extends LitElement {
    * ```
    */
   accessor timeSliderSteps: number[] | number;
+  /**
+   * Time zone mode. Not supported after the component has loaded.
+   *
+   * @internal
+   */
+  accessor timeZoneMode: "offset" | "region";
   /**
    * The difference in hours between UTC time and the time displayed in the component.
    *
+   * In sunlight mode, changing only this property preserves the current `SunLighting.date` instant and recomputes
+   * displayed local date/time in the new offset. When this property changes together with
+   * [localDate](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#localDate) and/or [timeSliderPosition](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#timeSliderPosition),
+   * the date/time values are applied as one local selection and a new lighting instant is written.
+   * This property is separate from [arcgis-scene.timeZone](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#timeZone). Changing one does not update the other.
+   *
    * @example
    * ```js
+   * // Change display timezone while preserving the same scene lighting instant.
    * daylight.utcOffset = -8;
    * ```
    * @example
    * ```js
+   * // Apply timezone and local date/time together to write a new lighting instant.
+   * daylight.utcOffset = -8;
+   * daylight.localDate = "2025-01-15";
+   * daylight.timeSliderPosition = 16 * 60;
+   * ```
+   * @example
+   * ```js
    * // Alternatively, the UTC offset can be set by configuring the `displayUTCOffset` property of `SunLighting`.
    * viewElement.environment.lighting = new SunLighting({
    *   displayUTCOffset: -8
@@ -261,14 +312,17 @@ export abstract class ArcgisDaylight extends LitElement {
    */
   accessor utcOffset: number | null | undefined;
   /**
-   * The view associated with the component. 
-   *   > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-daylight component will be associated with a map or scene component rather than using the `view` property.
+   * The view associated with the component.
+   * > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-daylight component will be associated with a map or scene component rather than using the `view` property.
    */
   accessor view: SceneView | undefined;
   /**
    * Starts or pauses the date animation cycling through the months of the year.
    * Set the property to `true` to start the animation and to `false` to pause it.
    *
+   * `yearPlaying` and [dayPlaying](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#dayPlaying) are mutually exclusive.
+   * When virtual lighting is active, playback is stopped.
+   *
    * @default false
    */
   accessor yearPlaying: boolean;
@@ -277,12 +331,15 @@ export abstract class ArcgisDaylight extends LitElement {
   "@setterTypes": {
     localDate?: Date | number | string;
   };
-  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
+  /** Emitted when the component associated with a map or scene view is ready for user interaction. */
   readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
   /**
    * Fires when the user changes the date or time in the component by interacting with the slider, the date picker, the
    * season selector or the play buttons.
    *
+   * This event is user-action only. It does not fire for internal synchronization (for example, initial state sync
+   * when the view becomes ready).
+   *
    * @since 4.33
    */
   readonly arcgisUserDateTimeChange: import("@arcgis/lumina").TargetedEvent<this, void>;