SceneTimeRange: onTimeZoneChange and onTimeRangeChange to set

docusaurus/docs/advanced-data.md

@@ -65,6 +65,30 @@ The subscription returned from `sourceData.subscribeToState` is added to `this._
 
 Similarly to data, you can use the closest time range in a custom scene object using `sceneGraph.getTimeRange(model)`. This method can be used both in the custom object class and the renderer, as described previously in the [Use data](#use-data) section.
 
+Sometimes you may need to update a time range dynamically. You can do this by using the `setTimeRange` method.
+
+```tsx
+import { SceneTimeRange } from '@grafana/scenes';
+import { toUtc } from '@grafana/data';
+...
+
+const localTimeRange = new SceneTimeRange(); // Timerange defaults to the last six hours
+
+...
+
+const from = toUtc(1696405657);
+const to = toUtc(1696405687);
+
+localTimeRange.setTimeRange({
+  raw: {
+    from,
+    to
+  }
+  from,
+  to
+});
+```
+
 ## Source code
 
 [View the example source code](https://github.com/grafana/scenes/tree/main/docusaurus/docs/advanced-data.tsx)

packages/scenes/src/core/SceneTimeRange.test.tsx

@@ -58,14 +58,14 @@ describe('SceneTimeRange', () => {
     const timeRange = new SceneTimeRange({ from: 'now-1h', to: 'now' });
     const stateSpy = jest.spyOn(timeRange, 'setState');
 
-    timeRange.onTimeRangeChange({
+    timeRange.setTimeRange({
       from: toUtc('2020-01-01'),
       to: toUtc('2020-01-02'),
       raw: { from: toUtc('2020-01-01'), to: toUtc('2020-01-02') },
     });
     expect(stateSpy).toBeCalledTimes(1);
 
-    timeRange.onTimeRangeChange({
+    timeRange.setTimeRange({
       from: toUtc('2020-01-01'),
       to: toUtc('2020-01-02'),
       raw: { from: toUtc('2020-01-01'), to: toUtc('2020-01-02') },

packages/scenes/src/core/SceneTimeRange.tsx

@@ -95,7 +95,12 @@ export class SceneTimeRange extends SceneObjectBase<SceneTimeRangeState> impleme
     return getTimeZone();
   }
 
+  /** @deprecated Use `setTimeRange` instead. */
   public onTimeRangeChange = (timeRange: TimeRange) => {
+    this.setTimeRange(timeRange);
+  };
+
+  public setTimeRange = (timeRange: TimeRange) => {
     const update: Partial<SceneTimeRangeState> = {};
 
     if (typeof timeRange.raw.from === 'string') {
@@ -118,7 +123,12 @@ export class SceneTimeRange extends SceneObjectBase<SceneTimeRangeState> impleme
     }
   };
 
+  /** @deprecated Use `setTimeZone` instead.*/
   public onTimeZoneChange = (timeZone: TimeZone) => {
+    this.setTimeZone(timeZone);
+  };
+
+  public setTimeZone = (timeZone: TimeZone) => {
     this.setState({ timeZone });
   };
 

packages/scenes/src/core/SceneTimeRangeTransformerBase.tsx

@@ -41,12 +41,21 @@ export abstract class SceneTimeRangeTransformerBase<T extends SceneTimeRangeStat
     return this.getAncestorTimeRange().getTimeZone();
   }
 
+  /** @deprecated */
   public onTimeRangeChange(timeRange: TimeRange): void {
-    this.getAncestorTimeRange().onTimeRangeChange(timeRange);
+    this.setTimeRange(timeRange);
   }
 
+  /** @deprecated */
   public onTimeZoneChange(timeZone: string): void {
-    this.getAncestorTimeRange().onTimeZoneChange(timeZone);
+    this.setTimeZone(timeZone);
+  }
+
+  public setTimeZone(timeZone: string): void {
+    this.getAncestorTimeRange().setTimeZone(timeZone);
+  }
+  public setTimeRange(timeRange: TimeRange): void {
+    this.getAncestorTimeRange().setTimeRange(timeRange);
   }
 
   public onRefresh(): void {

packages/scenes/src/core/SceneTimeZoneOverride.tsx

@@ -35,7 +35,7 @@ export class SceneTimeZoneOverride
     return this.state.timeZone;
   }
 
-  public onTimeZoneChange(timeZone: string): void {
+  public setTimeZone(timeZone: string) {
     this.setState({
       timeZone,
       value: evaluateTimeRange(
@@ -46,4 +46,8 @@ export class SceneTimeZoneOverride
       ),
     });
   }
+  /** @deprecated */
+  public onTimeZoneChange(timeZone: string): void {
+    this.setTimeZone(timeZone);
+  }
 }

packages/scenes/src/core/types.ts

@@ -147,8 +147,14 @@ export interface SceneTimeRangeState extends SceneObjectState {
 }
 
 export interface SceneTimeRangeLike extends SceneObject<SceneTimeRangeState> {
+  /** @deprecated Use `setTimeZone` instead. */
   onTimeZoneChange(timeZone: TimeZone): void;
+  /** Set the time zone. Thing wrapper around `setState` */
+  setTimeZone(timeZone: TimeZone): void;
+  /** @deprecated Use `setTimeRange` instead. */
   onTimeRangeChange(timeRange: TimeRange): void;
+  /** Set the timerange. Implicitly handle things that are not done when using `setState` */
+  setTimeRange(timeRange: TimeRange): void;
   onRefresh(): void;
   getTimeZone(): TimeZone;
 }