@arcgis/map-components 5.0.0-next.2 → 5.0.0-next.20

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

@@ -4,7 +4,7 @@ import { Use } from '@arcgis/lumina/controllers';
 import { PublicLitElement as LitElement, JsxNode, TargetedEvent } from '@arcgis/lumina';
 import { ArcgisReferenceElement } from '../../utils/component-utils';
 import { HeadingLevel } from '../../support/heading';
-import { LightingUnion, Season } from './daylight-utils';
+import { Season } from './daylight-utils';
 import { useView } from '../../controllers/useView';
 import { default as SceneView } from '@arcgis/core/views/SceneView';
 import { default as LinkChartView } from '@arcgis/core/views/LinkChartView';
@@ -14,15 +14,60 @@ import { PropertyValues } from 'lit';
 type ActivePlayingState = "day" | "year";
 type PlayingState = ActivePlayingState | "none";
 /**
- * The Daylight component can be used to manipulate the lighting conditions of a [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/).
+ * The Daylight component can be used to manipulate the lighting conditions of a
+ * [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/).
+ * For this, the component modifies the `lighting` property of the
+ * [environment](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#environment) of the Scene component.
  *
- * **Known limitations**
+ * To illuminate the scene, one can either use a configuration of date and time to position the
+ * [sun](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-SunLighting.html) or switch to the
+ * [virtual mode](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-VirtualLighting.html) mode,
+ * where the light source is relative to the camera.
  *
- * Daylight is only supported in a 3D [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/) component.
+ * When **lighting the scene with the sun** and adjusting the time and date, the position of the sun
+ * and the stars get updated accordingly, changing the light and the shadows in the scene. This sets the `date` and `directShadowsEnabled` properties of
+ * [environment.lighting](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#environment).
+ *
+ * [![daylight-default](https://developers.arcgis.com/javascript/latest/assets/img/apiref/components/daylight/daylight-default.png)](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
+ * in the chosen timezone is calculated and displayed in the slider. The timezone selector can be disabled
+ * by using `hide-timezone` attribute or setting `hideTimezone` property to `true`.
+ *
+ * By default, a calendar is displayed where the user can select the day, month and year.
+ * With the [dateOrSeason](#dateOrSeason) property, the calendar can be replaced with
+ * a dropdown menu where a season can be selected instead:
+ *
+ * ![daylight-seasons](https://developers.arcgis.com/javascript/latest/assets/img/apiref/components/daylight/daylight-seasons.png)
+ *
+ * There are two play buttons, one corresponds to the daytime slider and it animates the time as
+ * it cycles through the minutes of the day. The second button corresponds to the date picker
+ * and it animates the time as it cycles through the months of the year. The speed of the animation can
+ * be set using the [playSpeedMultiplier](#playSpeedMultiplier) property.
+ *
+ * ![daylight-animation](https://developers.arcgis.com/javascript/latest/assets/img/apiref/components/daylight/daylight-animation.gif)
+ *
+ * Except for the daytime slider, all the elements in the Daylight component can be hidden:
+ *
+ * ![daylight-no-elements](https://developers.arcgis.com/javascript/latest/assets/img/apiref/components/daylight/daylight-no-elements.png)
+ *
+ * Whenever the sun position option is unchecked, the scene applies the **virtual light source** relative to the camera.
+ * With this, the component's time slider, timezone and date picker get automatically disabled:
+ *
+ * ![daylight-virtual](https://developers.arcgis.com/javascript/latest/assets/img/apiref/components/daylight/daylight-virtual.png)
+ *
+ * **Things to consider**
+ *
+ * * Daylight is only supported in a 3D [Scene](https://developers.arcgis.com/javascript/latest/references/map-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.
+ * * When the [environment.lighting](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#environment)
+ * is of the type `virtual`, setting the time and date does not have an influence on the lighting conditions of the scene.
  *
  * **See also**
  *
  * - [Environment](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#environment)
+ * - [SunLighting](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-SunLighting.html)
+ * - [VirtualLighting](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-VirtualLighting.html)
  * - [Sample - Daylight component](https://developers.arcgis.com/javascript/latest/sample-code/daylight/)
  *
  * [Read more...](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-daylight/)
@@ -33,12 +78,13 @@ export declare class ArcgisDaylight extends LitElement {
     view?: LinkChartView | MapView | SceneView;
     get playingState(): PlayingState;
     set playingState(value: PlayingState);
-    get lighting(): LightingUnion | nullish;
     /** @default false */
     get supported(): boolean;
     /**
-     * Indicates whether date and time are used to determine position of the light source.
-     * When `false`, the light source is positioned relative to the camera, using [VirtualLighting](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-VirtualLighting.html).
+     * When set, the light source is positioned relative to the camera, using
+     * [VirtualLighting](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-VirtualLighting.html).
+     * Otherwise, [date and time](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-SunLighting.html)
+     * are used to determine position of the light source.
      *
      * @default false
      */
@@ -55,28 +101,39 @@ export declare class ArcgisDaylight extends LitElement {
      */
     autoDestroyDisabled: boolean;
     /**
-     * A season can be set instead of a date.
+     * Sets the season that is used when the component displays a season picker.
      * Each season uses a fixed date corresponding to the seasonal equinoxes and solstices.
+     *
+     * **See also**
+     *
+     * [dateOrSeason](#dateOrSeason)
      */
     get currentSeason(): Season;
     set currentSeason(season: Season);
     /**
-     * Controls whether the component displays a date or a season picker.
-     *
-     * [Read more](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Daylight.html#dateOrSeason)
+     * 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.
      *
      * @default "date"
      */
     dateOrSeason: "date" | "season";
     /**
      * Starts or pauses the daytime animation cycling through the minutes of the day.
-     * Set to `true` to start the animation and to `false` to pause it.
+     * Set the property to `true` to start the animation and to `false` to pause it.
      *
      * @default false
      */
     get dayPlaying(): boolean;
     set dayPlaying(playing: boolean);
-    /** @default false */
+    /**
+     * Indicates whether to hide shadows cast by the sun.
+     *
+     * **See also**
+     *
+     * - [SunLighting.directShadowsEnabled](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-SunLighting.html#directShadowsEnabled)
+     * - [Scene's `environment`](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/#environment)
+     *
+     * @default false
+     */
     get directShadowsDisabled(): boolean;
     set directShadowsDisabled(disabled: boolean);
     /**
@@ -112,11 +169,11 @@ export declare class ArcgisDaylight extends LitElement {
      *
      * @example
      * // Plays the daylight animation at half of the default speed
-     * daylightWidget.playSpeedMultiplier = 0.5;
+     * daylight.playSpeedMultiplier = 0.5;
      * @default 1.0
      */
     playSpeedMultiplier: number;
-    /** @deprecated since 4.34, use [`slot`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/slot) instead. */
+    /** @deprecated since 4.34, use [`slot`](https://developers.arcgis.com/javascript/latest/building-your-ui/#slots) instead. */
     position?: __esri.UIPosition;
     /**
      * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
@@ -125,17 +182,14 @@ export declare class ArcgisDaylight extends LitElement {
      */
     referenceElement?: ArcgisReferenceElement | string;
     /**
-     * Sets steps, or intervals, on the time slider to restrict the times of the day that can be selected when dragging the thumb.
-     * Sets steps, or intervals, on the time slider to restrict the times of the day that can be selected when dragging the thumb. All values are in minutes, where 0 is midnight and 23 * 60 + 59 is just before midnight the following day.
-     *
-     * If an array of numbers is passed to this property, the slider thumbs may only be moved to the times specified in the array.
+     * Sets the interval, in minutes, with which the time slider increments or decrements as it is dragged or changed via the keyboard.
      *
-     * If a single number is set, then steps are set for the entire day at an interval of timeSliderSteps minutes. For example, if a value of 60 is set here, dragging the slider will allow selecting each of 24 hours of the day.
+     * For example, if set to 60, the slider will allow selecting each hour of the day.
      *
      * @default 5
      */
     timeSliderSteps: number;
-    /** The difference in hours between UTC time and the time displayed in the widget. */
+    /** The difference in hours between UTC time and the time displayed in the component. */
     get utcOffset(): nullish | number;
     set utcOffset(value: nullish | number);
     /**
@@ -143,29 +197,19 @@ export declare class ArcgisDaylight extends LitElement {
      * given by [utcOffset](#utcOffset). The position represents the time
      * of the day in minutes. Possible values range between 0 and 1440.
      *
-     * This property should only be set once the widget and the view are initialized, for example,
-     * from within an event handler. To initialize the view with a specific date and time, set a
-     * [SunLighting](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-SunLighting.html) on the [SceneView.environment](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html#environment).
-     *
      * @example
-     * view.environment.lighting = new SunLighting({
+     * viewElement.environment.lighting = new SunLighting({
      *   date: new Date("2022-06-21T12:00:00")
      * });
      */
     get timeSliderPosition(): nullish | number;
     set timeSliderPosition(value: nullish | number);
-    /**
-     * The calendar date in the timezone given by [utcOffset](#utcOffset).
-     *
-     * This property should only be set once the widget and the view are initialized, for example,
-     * from within an event handler. To initialize the view with a specific date and time, set a
-     * [SunLighting](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-environment-SunLighting.html) on the [SceneView.environment](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html#environment).
-     */
+    /** The calendar date in the timezone given by [utcOffset](#utcOffset). */
     get localDate(): Date;
     set localDate(value: Date | number | string);
     /**
-     * Starts or pauses the date animation cycling through the months of the year. Set to `true` to start the animation
-     * and to `false` to pause it.
+     * 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.
      *
      * @default false
      */