@itwin/core-frontend 3.3.0-dev.9 → 3.3.2

package/lib/esm/DisplayStyleState.js

@@ -14,7 +14,6 @@ import { ContextRealityModelState } from "./ContextRealityModelState";
 import { ElementState } from "./EntityState";
 import { IModelApp } from "./IModelApp";
 import { PlanarClipMaskState } from "./PlanarClipMaskState";
-import { RenderScheduleState } from "./RenderScheduleState";
 import { getCesiumOSMBuildingsUrl, MapCartoRectangle } from "./tile/internal";
 import { viewGlobalLocation, ViewGlobalLocationConstants } from "./ViewGlobalLocation";
 import { GeometricModelState } from "./ModelState";
@@ -34,13 +33,18 @@ export class DisplayStyleState extends ElementState {
     constructor(props, iModel, source) {
         super(props, iModel);
         this._attachedRealityModelPlanarClipMasks = new Map();
-        /** Event raised just before the [[scheduleScriptReference]] property is changed. */
+        this._assigningScript = false;
+        /** Event raised just before the [[scheduleScriptReference]] property is changed.
+         * @deprecated use [[onScheduleScriptChanged]].
+         */
         this.onScheduleScriptReferenceChanged = new BeEvent();
+        /** Event raised just before the [[scheduleScript]] property is changed. */
+        this.onScheduleScriptChanged = new BeEvent();
         /** Event raised just after [[setOSMBuildingDisplay]] changes the enabled state of the OSM buildings. */
         this.onOSMBuildingDisplayChanged = new BeEvent();
         const styles = this.jsonProperties.styles;
         if (source)
-            this._scheduleState = source._scheduleState;
+            this._scriptReference = source._scriptReference;
         if (styles) {
             // ###TODO Use DisplayStyleSettings.planarClipMasks
             if (styles.planarClipOvr)
@@ -57,61 +61,64 @@ export class DisplayStyleState extends ElementState {
     async load() {
         // If we were cloned, we may already have a valid schedule state, and our display style Id may be invalid / different.
         // Preserve it if still usable.
-        if (this._scheduleState) {
-            if (this.settings.renderTimeline === this._scheduleState.sourceId) {
+        if (this._scriptReference) {
+            if (this.settings.renderTimeline === this._scriptReference.sourceId) {
                 // The script came from the same RenderTimeline element. Keep it.
                 return;
             }
             if (undefined === this.settings.renderTimeline) {
-                // The script cam from a display style's JSON properties. Keep it if (1) this style is not persistent or (2) this style has the same Id
-                if (this.id === this._scheduleState.sourceId || !Id64.isValidId64(this.id))
+                // The script came from a display style's JSON properties. Keep it if (1) this style is not persistent or (2) this style has the same Id
+                if (this.id === this._scriptReference.sourceId || !Id64.isValidId64(this.id))
                     return;
             }
         }
-        if (undefined !== this.settings.renderTimeline)
-            await this.loadScheduleStateFromTimeline(this.settings.renderTimeline);
+        // The schedule script stored in JSON properties takes precedence over the RenderTimeline if both are defined.
+        if (this.settings.scheduleScriptProps)
+            this.loadScriptReferenceFromScript(this.settings.scheduleScriptProps);
         else
-            this.loadScheduleStateFromScript(this.settings.scheduleScriptProps); // eslint-disable-line deprecation/deprecation
+            await this.loadScriptReferenceFromTimeline(this.settings.renderTimeline);
     }
-    loadScheduleStateFromScript(scriptProps) {
+    loadScriptReferenceFromScript(scriptProps) {
         let newState;
-        if (scriptProps) {
-            try {
-                const script = RenderSchedule.Script.fromJSON(scriptProps);
-                if (script)
-                    newState = new RenderScheduleState(this.id, script);
-            }
-            catch (_) {
-                // schedule state is undefined.
-            }
+        try {
+            const script = RenderSchedule.Script.fromJSON(scriptProps);
+            if (script)
+                newState = new RenderSchedule.ScriptReference(this.id, script);
         }
-        if (newState !== this._scheduleState) {
-            this.onScheduleScriptReferenceChanged.raiseEvent(newState);
-            this._scheduleState = newState;
+        catch (_) {
+            // schedule state is undefined.
+        }
+        if (newState !== this._scriptReference) {
+            this.onScheduleScriptReferenceChanged.raiseEvent(newState); // eslint-disable-line deprecation/deprecation
+            this.onScheduleScriptChanged.raiseEvent(newState === null || newState === void 0 ? void 0 : newState.script);
+            this._scriptReference = newState;
         }
     }
-    async loadScheduleStateFromTimeline(timelineId) {
+    async loadScriptReferenceFromTimeline(timelineId) {
         let newState;
-        try {
-            // If a subsequent call to loadScheduleStateFromTimeline is made while we're awaiting this one, we'll abort this one.
-            const promise = this._queryRenderTimelinePropsPromise = this.queryRenderTimelineProps(timelineId);
-            const timeline = await promise;
-            if (promise !== this._queryRenderTimelinePropsPromise)
-                return;
-            if (timeline) {
-                const scriptProps = JSON.parse(timeline.script);
-                const script = RenderSchedule.Script.fromJSON(scriptProps);
-                if (script)
-                    newState = new RenderScheduleState(timelineId, script);
+        if (timelineId && Id64.isValidId64(timelineId)) {
+            try {
+                // If a subsequent call to loadScriptReferenceFromTimeline is made while we're awaiting this one, we'll abort this one.
+                const promise = this._queryRenderTimelinePropsPromise = this.queryRenderTimelineProps(timelineId);
+                const timeline = await promise;
+                if (promise !== this._queryRenderTimelinePropsPromise)
+                    return;
+                if (timeline) {
+                    const scriptProps = JSON.parse(timeline.script);
+                    const script = RenderSchedule.Script.fromJSON(scriptProps);
+                    if (script)
+                        newState = new RenderSchedule.ScriptReference(timelineId, script);
+                }
+            }
+            catch (_) {
+                // schedule state is undefined.
             }
-        }
-        catch (_) {
-            // schedule state is undefined.
         }
         this._queryRenderTimelinePropsPromise = undefined;
-        if (newState !== this._scheduleState) {
-            this.onScheduleScriptReferenceChanged.raiseEvent(newState);
-            this._scheduleState = newState;
+        if (newState !== this._scriptReference) {
+            this.onScheduleScriptReferenceChanged.raiseEvent(newState); // eslint-disable-line deprecation/deprecation
+            this.onScheduleScriptChanged.raiseEvent(newState === null || newState === void 0 ? void 0 : newState.script);
+            this._scriptReference = newState;
         }
     }
     /** @internal */
@@ -129,9 +136,9 @@ export class DisplayStyleState extends ElementState {
     }
     /** @internal */
     get globeMode() { return this.settings.backgroundMap.globeMode; }
-    /** @internal */
-    get backgroundMapLayers() { return this.settings.mapImagery.backgroundLayers; }
-    /** @beta */
+    /** Settings controlling how the base map is displayed within a view.
+     *  The base map can be provided by any map imagery source or set to be a single color.
+     */
     get backgroundMapBase() {
         return this.settings.mapImagery.backgroundBase;
     }
@@ -140,6 +147,8 @@ export class DisplayStyleState extends ElementState {
         this._synchBackgroundMapImagery();
     }
     /** @internal */
+    get backgroundMapLayers() { return this.settings.mapImagery.backgroundLayers; }
+    /** @internal */
     get overlayMapLayers() { return this.settings.mapImagery.overlayLayers; }
     /** The settings controlling how a background map is displayed within a view.
      * @see [[ViewFlags.backgroundMap]] for toggling display of the map on or off.
@@ -157,6 +166,7 @@ export class DisplayStyleState extends ElementState {
      * ``` ts
      *  style.changeBackgroundMapProps({ groundBias: 16.2 });
      * ```
+     * @public
      */
     changeBackgroundMapProps(props) {
         const newSettings = this.backgroundMapSettings.clone(props);
@@ -207,14 +217,14 @@ export class DisplayStyleState extends ElementState {
     /** The name of this DisplayStyle */
     get name() { return this.code.value; }
     /** Change the Id of the [RenderTimeline]($backend) element that hosts the [RenderSchedule.Script]($common) to be applied by this display style for
-     * animating the contents of the view, and update [[scheduleScriptReference]] using the script associated with the [RenderTimeline]($backend) element.
+     * animating the contents of the view, and update [[scheduleScript]] using the script associated with the [RenderTimeline]($backend) element.
      * @see [DisplayStyleSettings.renderTimeline]($common).
      */
     async changeRenderTimeline(timelineId) {
         // Potentially trigger async loading of new schedule state.
         this.settings.renderTimeline = timelineId;
         // Await async loading if necessary.
-        // Note the `await` in loadScheduleStateFromTimeline will resolve before this one [per the spec](https://262.ecma-international.org/6.0/#sec-triggerpromisereactions).
+        // Note the `await` in loadScriptReferenceFromTimeline will resolve before this one [per the spec](https://262.ecma-international.org/6.0/#sec-triggerpromisereactions).
         if (this._queryRenderTimelinePropsPromise)
             await this._queryRenderTimelinePropsPromise;
     }
@@ -223,30 +233,31 @@ export class DisplayStyleState extends ElementState {
      */
     get scheduleScript() {
         var _a;
-        return (_a = this._scheduleState) === null || _a === void 0 ? void 0 : _a.script;
+        return (_a = this._scriptReference) === null || _a === void 0 ? void 0 : _a.script;
+    }
+    set scheduleScript(script) {
+        if (script === this.scheduleScript)
+            return;
+        try {
+            const scriptRef = script ? new RenderSchedule.ScriptReference(script) : undefined;
+            this.onScheduleScriptReferenceChanged.raiseEvent(scriptRef); // eslint-disable-line deprecation/deprecation
+            this.onScheduleScriptChanged.raiseEvent(script);
+            this._scriptReference = scriptRef;
+            this._assigningScript = true;
+            this.settings.scheduleScriptProps = script === null || script === void 0 ? void 0 : script.toJSON();
+            if (!script)
+                this.loadScriptReferenceFromTimeline(this.settings.renderTimeline); // eslint-disable-line @typescript-eslint/no-floating-promises
+        }
+        finally {
+            this._assigningScript = false;
+        }
     }
     /** The [RenderSchedule.Script]($common) that animates the contents of the view, if any, along with the Id of the element that hosts the script.
      * @note The host element may be a [RenderTimeline]($backend) or a [DisplayStyle]($backend).
-     * @see [[changeRenderTimeline]] to change the script.
+     * @deprecated Use [[scheduleScript]].
      */
     get scheduleScriptReference() {
-        return this._scheduleState;
-    }
-    /** @internal */
-    get scheduleState() {
-        return this._scheduleState;
-    }
-    /** This is only used by [RealityTransitionTool]($frontend-devtools). It basically can only work if the script contains nothing that requires special tiles to be generated -
-     * no symbology changes, transforms, or clipping - because the backend tile generator requires a *persistent* element to host the script for those features to work.
-     * @internal
-     */
-    setScheduleState(state) {
-        if (state === this._scheduleState)
-            return;
-        this.onScheduleScriptReferenceChanged.raiseEvent(state);
-        this._scheduleState = state;
-        // eslint-disable-next-line deprecation/deprecation
-        this.settings.scheduleScriptProps = state === null || state === void 0 ? void 0 : state.script.toJSON();
+        return this._scriptReference;
     }
     /** Attach a [ContextRealityModel]($common) to this display style.
      * @see [DisplayStyleSettings.contextRealityModels]($common).
@@ -311,11 +322,21 @@ export class DisplayStyleState extends ElementState {
     }
     /** @internal */
     getMapLayers(isOverlay) { return isOverlay ? this.overlayMapLayers : this.backgroundMapLayers; }
-    /** @internal */
-    attachMapLayerSettings(settings, isOverlay, insertIndex = -1) {
-        const layerSettings = settings.clone({});
+    /**
+     * Attach a map layer to display style.
+     * @param Settings representing the map layer.
+     * @param isOverlay true if layer is overlay, otherwise layer is background. Defaults to false.
+     * @param index where the layer should be inserted. Defaults to -1, appended to end.
+     * @public
+     *
+     */
+    attachMapLayer(options) {
+        var _a, _b;
+        const layerSettings = options.settings.clone({});
         if (undefined === layerSettings)
             return;
+        const isOverlay = (_a = options.isOverlay) !== null && _a !== void 0 ? _a : false;
+        const insertIndex = (_b = options.insertIndex) !== null && _b !== void 0 ? _b : -1;
         const layers = this.getMapLayers(isOverlay);
         if (insertIndex < 0 || insertIndex > (layers.length - 1)) {
             this.getMapLayers(isOverlay).push(layerSettings);
@@ -326,11 +347,11 @@ export class DisplayStyleState extends ElementState {
         this._synchBackgroundMapImagery();
     }
     /** @internal */
-    attachMapLayer(props, isOverlay, insertIndex = -1) {
-        const layerSettings = MapLayerSettings.fromJSON(props);
-        if (undefined === layerSettings)
+    attachMapLayerProps(options) {
+        const settings = MapLayerSettings.fromJSON(options.props);
+        if (undefined === settings)
             return;
-        this.attachMapLayerSettings(layerSettings, isOverlay, insertIndex);
+        this.attachMapLayer({ settings, isOverlay: options.isOverlay, insertIndex: options.insertIndex });
     }
     /** @internal */
     hasAttachedMapLayer(name, source, isOverlay) {
@@ -343,7 +364,7 @@ export class DisplayStyleState extends ElementState {
             this.detachMapLayerByIndex(index, isOverlay);
     }
     /** Detach map layer at index (-1 to remove all layers)
-     * @internal
+     * @public
      */
     detachMapLayerByIndex(index, isOverlay) {
         const layers = this.getMapLayers(isOverlay);
@@ -353,22 +374,31 @@ export class DisplayStyleState extends ElementState {
             layers.splice(index, 1);
         this._synchBackgroundMapImagery();
     }
-    /** @internal */
+    /**
+     * Lookup a maplayer index by name and source.
+     * @param name Name of of the layer.
+     * @param source Unique string identifying the layer.
+     * @param isOverlay true if layer is overlay, otherwise layer is background. Defaults to false.
+     * @public
+     *
+     */
     findMapLayerIndexByNameAndSource(name, source, isOverlay) {
         return this.getMapLayers(isOverlay).findIndex((layer) => layer.matchesNameAndSource(name, source));
     }
-    /** @internal */
+    /** @public */
     mapLayerAtIndex(index, isOverlay) {
         const layers = this.getMapLayers(isOverlay);
         return (index < 0 || index >= layers.length) ? undefined : layers[index];
     }
     /** Return map base transparency as a number between 0 and 1.
-     * @internal
+     * @public
      */
     get baseMapTransparency() {
         return this.settings.mapImagery.baseTransparency;
     }
-    /** @internal  */
+    /** Change the map base transparency as a number between 0 and 1.
+     * @public
+     */
     changeBaseMapTransparency(transparency) {
         if (this.settings.mapImagery.backgroundBase instanceof ColorDef) {
             this.settings.mapImagery.backgroundBase = this.settings.mapImagery.backgroundBase.withTransparency(transparency * 255);
@@ -378,7 +408,17 @@ export class DisplayStyleState extends ElementState {
         }
         this._synchBackgroundMapImagery();
     }
-    /** @internal */
+    /** Modify a subset of a map layer settings.
+     * @param props props JSON representation of the properties to change. Any properties not present will retain their current values.
+     * @param index where the layer should be inserted.
+     * @param isOverlay true if layer is overlay, otherwise layer is background.
+     *
+     * Example that changes only the visibility of the first overlay map layer.
+     * ``` ts
+     *  style.changeMapLayerProps({ visible: false }, 0, false);
+     * ```
+     * @public
+     */
     changeMapLayerProps(props, index, isOverlay) {
         const layers = this.getMapLayers(isOverlay);
         if (index < 0 || index >= layers.length)
@@ -386,6 +426,7 @@ export class DisplayStyleState extends ElementState {
         layers[index] = layers[index].clone(props);
         this._synchBackgroundMapImagery();
     }
+    /** @public */
     changeMapLayerCredentials(index, isOverlay, userName, password) {
         const layers = this.getMapLayers(isOverlay);
         if (index < 0 || index >= layers.length)
@@ -396,6 +437,14 @@ export class DisplayStyleState extends ElementState {
             this._synchBackgroundMapImagery();
         }
     }
+    /** Modify a subset of a sub-layer settings.
+     * @param props props JSON representation of the properties to change. Any properties not present will retain their current values.
+     * @param subLayerId Id of the sub-layer that should be modified.
+     * @param layerIndex of the owning map layer.
+     * @param isOverlay true if the map layer is overlay, otherwise layer is background
+     *
+     * @public
+     */
     changeMapSubLayerProps(props, subLayerId, layerIndex, isOverlay) {
         const mapLayerSettings = this.mapLayerAtIndex(layerIndex, isOverlay);
         if (undefined === mapLayerSettings)
@@ -410,7 +459,12 @@ export class DisplayStyleState extends ElementState {
         }
         this.changeMapLayerProps({ subLayers }, layerIndex, isOverlay);
     }
-    /** @internal */
+    /** Returns the cartographic range of map layer.
+     * @param layerIndex of the map layer.
+     * @param isOverlay true if the map layer is overlay, otherwise layer is background
+     *
+     * @internal
+     */
     async getMapLayerRange(layerIndex, isOverlay) {
         var _a;
         const mapLayerSettings = this.mapLayerAtIndex(layerIndex, isOverlay);
@@ -464,7 +518,7 @@ export class DisplayStyleState extends ElementState {
      * Move map layer to top.
      * @param index index of layer to move.
      * @param isOverlay true if layer is overlay.
-     * @internal
+     * @public
      *
      */
     moveMapLayerToTop(index, isOverlay) {
@@ -479,7 +533,7 @@ export class DisplayStyleState extends ElementState {
      * Move map layer to bottom.
      * @param index index of layer to move.
      * @param isOverlay true if layer is overlay.
-     * @internal
+     * @public
      */
     moveMapLayerToBottom(index, isOverlay) {
         const layers = this.getMapLayers(isOverlay);
@@ -493,7 +547,7 @@ export class DisplayStyleState extends ElementState {
      * Reorder map layers
      * @param fromIndex index of map layer to move
      * @param toIndex insert index. If equal to length of map array the map layer is moved to end of array.
-     * @internal
+     * @public
      */
     moveMapLayerToIndex(fromIndex, toIndex, isOverlay) {
         const layers = this.getMapLayers(isOverlay);
@@ -609,18 +663,25 @@ export class DisplayStyleState extends ElementState {
     }
     /** @internal */
     registerSettingsEventListeners() {
-        // eslint-disable-next-line deprecation/deprecation
         this.settings.onScheduleScriptPropsChanged.addListener((scriptProps) => {
-            if (undefined === this.settings.renderTimeline)
-                this.loadScheduleStateFromScript(scriptProps);
+            if (this._assigningScript)
+                return;
+            try {
+                this._assigningScript = true;
+                if (scriptProps)
+                    this.loadScriptReferenceFromScript(scriptProps);
+                else
+                    this.loadScriptReferenceFromTimeline(this.settings.renderTimeline); // eslint-disable-line @typescript-eslint/no-floating-promises
+            }
+            finally {
+                this._assigningScript = false;
+            }
         });
         this.settings.onRenderTimelineChanged.addListener((newTimeline) => {
             // Cancel any in-progress loading of script from timeline.
             this._queryRenderTimelinePropsPromise = undefined;
-            if (undefined !== newTimeline)
-                this.loadScheduleStateFromTimeline(newTimeline); // eslint-disable-line @typescript-eslint/no-floating-promises
-            else
-                this.loadScheduleStateFromScript(this.settings.scheduleScriptProps); // eslint-disable-line deprecation/deprecation
+            if (!this.settings.scheduleScriptProps)
+                this.loadScriptReferenceFromTimeline(newTimeline); // eslint-disable-line @typescript-eslint/no-floating-promises
         });
         this.settings.onPlanarClipMaskChanged.addListener((id, newSettings) => {
             if (newSettings)