@grafana/scenes 0.0.20 → 0.0.21

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import React, { CSSProperties } from 'react';
-import { Observable, Observer, SubscriptionLike, Unsubscribable, MonoTypeOperatorFunction, Subscription } from 'rxjs';
-import { BusEventWithPayload, PanelData, BusEvent, BusEventType, BusEventHandler, TimeZone, TimeRange, DataTransformContext, DataFrame, ScopedVars, DataSourceRef, DataQuery, DataTransformerConfig, Registry, RegistryItem, VariableRefresh, VariableSort, FieldConfigSource, PanelPlugin, AbsoluteTimeRange, InterpolateFunction, IconName as IconName$1 } from '@grafana/data';
-import { VariableType, VariableHide, VariableModel } from '@grafana/schema';
+import { Observable, Unsubscribable, MonoTypeOperatorFunction, Subscription } from 'rxjs';
+import { BusEventWithPayload, PanelData, BusEvent, BusEventType, BusEventHandler, TimeZone, TimeRange, DataTransformContext, DataFrame, ScopedVars, DataTransformerConfig, Registry, RegistryItem, DataSourceRef as DataSourceRef$1, VariableRefresh, VariableSort, PanelMenuItem, FieldConfigSource, PanelPlugin, AbsoluteTimeRange, InterpolateFunction, IconName as IconName$1 } from '@grafana/data';
+import { VariableType, VariableHide, VariableModel, DataSourceRef, DataQuery } from '@grafana/schema';
 import { IconName } from '@grafana/ui';
 import ReactGridLayout from 'react-grid-layout';
 
@@ -117,7 +117,7 @@ interface SceneObject<TState extends SceneObjectState = SceneObjectState> {
     /** This abstraction declares URL sync dependencies of a scene object. **/
     readonly urlSync?: SceneObjectUrlSyncHandler<TState>;
     /** Subscribe to state changes */
-    subscribeToState(observer?: Partial<Observer<TState>>): SubscriptionLike;
+    subscribeToState(handler: SceneStateChangedHandler<TState>): Unsubscribable;
     /** Subscribe to a scene event */
     subscribeToEvent<T extends BusEvent>(typeFilter: BusEventType<T>, handler: BusEventHandler<T>): Unsubscribable;
     /** Publish an event and optionally bubble it up the scene */
@@ -126,9 +126,14 @@ interface SceneObject<TState extends SceneObjectState = SceneObjectState> {
     useState(): TState;
     /** How to modify state */
     setState(state: Partial<TState>): void;
-    /** Called when the Component is mounted. A place to register event listeners add subscribe to state changes */
+    /**
+     * Called when the Component is mounted. This will also activate any $data, $variables or $timeRange scene object on this level.
+     * Don't override this in your custom SceneObjects, instead use addActivationHandler from the constructor. The activation handler can return a deactivation handler.
+     **/
     activate(): void;
-    /** Called when component unmounts. Unsubscribe and closes all subscriptions  */
+    /** Called when component unmounts. This will also deactivate any $data, $variables or $timeRange scene object on this level.
+     * Don't override this in your custom SceneObjects, instead use addActivationHandler from the constructor. The activation handler can return a deactivation handler.
+     */
     deactivate(): void;
     /** Get the scene root */
     getRoot(): SceneObject;
@@ -140,7 +145,14 @@ interface SceneObject<TState extends SceneObjectState = SceneObjectState> {
     Editor(props: SceneComponentProps<SceneObject<TState>>): React.ReactElement | null;
     /** Force a re-render, should only be needed when variable values change */
     forceRender(): void;
+    /**
+     * Allows external code to register code that is executed on activate and deactivate. This allow you
+     * to wire up scene objects that need to respond to state changes in other objects from the outside.
+     **/
+    addActivationHandler(handler: SceneActivationHandler): void;
 }
+type SceneActivationHandler = () => SceneDeactivationHandler | void;
+type SceneDeactivationHandler = () => void;
 type SceneLayoutChild = SceneObject<SceneLayoutChildState | SceneLayoutState>;
 interface SceneLayoutState extends SceneLayoutChildState {
     children: SceneLayoutChild[];
@@ -192,6 +204,7 @@ interface SceneObjectUrlSyncHandler<TState> {
 type SceneObjectUrlValue = string | string[] | undefined | null;
 type SceneObjectUrlValues = Record<string, SceneObjectUrlValue>;
 type CustomTransformOperator = (context: DataTransformContext) => MonoTypeOperatorFunction<DataFrame[]>;
+type SceneStateChangedHandler<TState> = (newState: TState, prevState: TState) => void;
 type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
@@ -257,9 +270,10 @@ declare const sceneGraph: {
 
 declare abstract class SceneObjectBase<TState extends SceneObjectState = SceneObjectState> implements SceneObject<TState> {
     private _isActive;
-    private _subject;
     private _state;
     private _events;
+    private _activationHandlers;
+    private _deactivationHandlers;
     protected _parent?: SceneObject;
     protected _subs: Subscription;
     protected _variableDependency: SceneVariableDependencyConfigLike | undefined;
@@ -288,7 +302,7 @@ declare abstract class SceneObjectBase<TState extends SceneObjectState = SceneOb
     /**
      * Subscribe to the scene state subject
      **/
-    subscribeToState(observerOrNext?: Partial<Observer<TState>>): SubscriptionLike;
+    subscribeToState(handler: SceneStateChangedHandler<TState>): Unsubscribable;
     /**
      * Subscribe to the scene event
      **/
@@ -297,11 +311,13 @@ declare abstract class SceneObjectBase<TState extends SceneObjectState = SceneOb
     publishEvent(event: BusEvent, bubble?: boolean): void;
     getRoot(): SceneObject;
     /**
-     * Called by the SceneComponentWrapper when the react component is mounted
+     * Called by the SceneComponentWrapper when the react component is mounted.
+     * Don't override this, instead use addActivationHandler
      */
     activate(): void;
     /**
-     * Called by the SceneComponentWrapper when the react component is unmounted
+     * Called by the SceneComponentWrapper when the react component is unmounted.
+     * Don't override this, instead use addActivationHandler. The activation handler can return a deactivation handler.
      */
     deactivate(): void;
     /**
@@ -314,6 +330,11 @@ declare abstract class SceneObjectBase<TState extends SceneObjectState = SceneOb
      * Will create new SceneObject with shallow-cloned state, but all state items of type SceneObject are deep cloned
      */
     clone(withState?: Partial<TState>): this;
+    /**
+     * Allows external code to register code that is executed on activate and deactivate. This allow you
+     * to wire up scene objects that need to respond to state changes in other objects from the outside.
+     **/
+    addActivationHandler(handler: SceneActivationHandler): void;
 }
 
 interface SceneDataNodeState extends SceneObjectStatePlain {
@@ -404,7 +425,8 @@ declare class SceneQueryRunner extends SceneObjectBase<QueryRunnerState> impleme
     private _containerWidth?;
     private _variableValueRecorder;
     protected _variableDependency: VariableDependencyConfig<QueryRunnerState>;
-    activate(): void;
+    constructor(initialState: QueryRunnerState);
+    private _onActivate;
     /**
      * Handles some tricky cases where we need to run queries even when they have not changed in case
      * the query execution on activate was stopped due to VariableSet still not having processed all variables.
@@ -434,9 +456,13 @@ interface SceneDataTransformerState extends SceneDataNodeState {
  * transformations that depend on other scene object states.
  */
 declare class SceneDataTransformer extends SceneObjectBase<SceneDataTransformerState> implements SceneDataProvider {
-    protected _variableDependency: VariableDependencyConfig<SceneDataTransformerState>;
     private _transformSub?;
-    activate(): void;
+    /**
+     * Scan transformations for variable usage and re-process transforms when a variable values change
+     */
+    protected _variableDependency: VariableDependencyConfig<SceneDataTransformerState>;
+    constructor(state: SceneDataTransformerState);
+    private activationHandler;
     private getSourceData;
     setContainerWidth(width: number): void;
     reprocessTransformations(): void;
@@ -493,20 +519,20 @@ declare class SceneVariableSet extends SceneObjectBase<SceneVariableSetState> im
     private _updating;
     private _variableValueRecorder;
     getByName(name: string): SceneVariable | undefined;
+    constructor(state: SceneVariableSetState);
     /**
-     * Subscribes to child variable value changes
-     * And starts the variable value validation process
+     * Subscribes to child variable value changes, and starts the variable value validation process
      */
-    activate(): void;
+    private _onActivate;
+    /**
+     * Cancel all currently running updates
+     */
+    private _onDeactivate;
     /**
      * If variables changed while in in-active state we don't get any change events, so we need to check for that here.
      */
     private checkForVariablesThatChangedWhileInactive;
     private variableNeedsUpdate;
-    /**
-     * Cancel all currently running updates
-     */
-    deactivate(): void;
     /**
      * This loops through variablesToUpdate and update all that that can.
      * If one has a dependency that is currently in variablesToUpdate it will be skipped for now.
@@ -616,7 +642,7 @@ declare class DataSourceVariable extends MultiValueVariable<DataSourceVariableSt
 
 interface QueryVariableState extends MultiValueVariableState {
     type: 'query';
-    datasource: DataSourceRef | null;
+    datasource: DataSourceRef$1 | null;
     query: any;
     regex: string;
     refresh: VariableRefresh;
@@ -626,7 +652,7 @@ declare class QueryVariable extends MultiValueVariable<QueryVariableState> {
     private updateSubscription?;
     protected _variableDependency: VariableDependencyConfig<QueryVariableState>;
     constructor(initialState: Partial<QueryVariableState>);
-    activate(): void;
+    private _onActivate;
     deactivate(): void;
     getValueOptions(args: VariableGetOptionsArgs): Observable<VariableValueOption[]>;
     private getRequest;
@@ -700,14 +726,13 @@ interface EmbeddedSceneState extends SceneObjectStatePlain {
 declare class EmbeddedScene extends SceneObjectBase<EmbeddedSceneState> {
     static Component: typeof EmbeddedSceneRenderer;
     private urlSyncManager?;
+    constructor(state: EmbeddedSceneState);
     /**
      * initUrlSync should be called before the scene is rendered to ensure that objects are in sync
      * before they get activated. This saves some unnecessary re-renders and makes sure variables
      * queries are issued as needed.
      */
     initUrlSync(): void;
-    activate(): void;
-    deactivate(): void;
 }
 declare function EmbeddedSceneRenderer({ model }: SceneComponentProps<EmbeddedScene>): JSX.Element;
 
@@ -716,6 +741,16 @@ declare namespace VizPanelRenderer {
     var displayName: string;
 }
 
+interface VizPanelMenuState extends SceneObjectStatePlain {
+    items?: PanelMenuItem[];
+}
+declare class VizPanelMenu extends SceneObjectBase<VizPanelMenuState> {
+    static Component: typeof VizPanelMenuRenderer;
+    addItem(item: PanelMenuItem): void;
+    setItems(items: PanelMenuItem[]): void;
+}
+declare function VizPanelMenuRenderer({ model }: SceneComponentProps<VizPanelMenu>): JSX.Element | null;
+
 interface VizPanelState<TOptions = {}, TFieldConfig = {}> extends SceneLayoutChildState {
     title: string;
     description?: string;
@@ -725,6 +760,7 @@ interface VizPanelState<TOptions = {}, TFieldConfig = {}> extends SceneLayoutChi
     pluginVersion?: string;
     displayMode?: 'default' | 'transparent';
     hoverHeader?: boolean;
+    menu?: VizPanelMenu;
     pluginLoadError?: string;
 }
 declare class VizPanel<TOptions = {}, TFieldConfig = {}> extends SceneObjectBase<VizPanelState<TOptions, TFieldConfig>> {
@@ -812,8 +848,6 @@ declare class SceneRefreshPicker extends SceneObjectBase<SceneRefreshPickerState
     protected _urlSync: SceneObjectUrlSyncConfig<SceneObjectState>;
     private _intervalTimer;
     constructor(state: Partial<SceneRefreshPickerState>);
-    activate(): void;
-    deactivate(): void;
     onRefresh: () => void;
     onIntervalChanged: (interval: string) => void;
     getUrlState(): {
@@ -824,12 +858,12 @@ declare class SceneRefreshPicker extends SceneObjectBase<SceneRefreshPickerState
 }
 declare function SceneRefreshPickerRenderer({ model }: SceneComponentProps<SceneRefreshPicker>): JSX.Element;
 
-interface RepeatOptions extends SceneObjectStatePlain {
+interface SceneByFrameRepeaterState extends SceneObjectStatePlain {
     body: SceneObject<SceneLayoutState>;
     getLayoutChild(data: PanelData, frame: DataFrame, frameIndex: number): SceneLayoutChild;
 }
-declare class SceneByFrameRepeater extends SceneObjectBase<RepeatOptions> {
-    activate(): void;
+declare class SceneByFrameRepeater extends SceneObjectBase<SceneByFrameRepeaterState> {
+    constructor(state: SceneByFrameRepeaterState);
     private performRepeat;
     static Component: ({ model, isEditing }: SceneComponentProps<SceneByFrameRepeater>) => JSX.Element;
 }
@@ -966,4 +1000,25 @@ declare class SceneAppPage extends SceneObjectBase<SceneAppPageState> {
 }
 declare function SceneAppPageRenderer({ model }: SceneComponentProps<SceneAppPage>): JSX.Element;
 
-export { ConstantVariable, CustomFormatterFn, CustomTransformOperator, CustomVariable, DataSourceVariable, DeepPartial, EmbeddedScene, EmbeddedSceneState, FormatRegistryID, FormatVariable, NestedScene, QueryRunnerState, QueryVariable, SceneApp, SceneAppDrilldownView, SceneAppPage, SceneAppPageLike, SceneAppPageState, SceneAppRoute, SceneByFrameRepeater, SceneCanvasText, SceneComponent, SceneComponentProps, SceneControlsSpacer, SceneDataNode, SceneDataProvider, SceneDataState, SceneDataTransformer, SceneEditor, SceneEditorState, SceneFlexLayout, SceneGridLayout, SceneGridRow, SceneLayout, SceneLayoutChild, SceneLayoutChildOptions, SceneLayoutChildState, SceneLayoutState, SceneObject, SceneObjectBase, SceneObjectRef, SceneObjectState, SceneObjectStateChangedEvent, SceneObjectStateChangedPayload, SceneObjectStatePlain, SceneObjectUrlSyncConfig, SceneObjectUrlSyncHandler, SceneObjectUrlValue, SceneObjectUrlValues, SceneObjectWithUrlSync, SceneQueryRunner, SceneRefreshPicker, SceneRouteMatch, SceneTimePicker, SceneTimeRange, SceneTimeRangeLike, SceneTimeRangeState, SceneToolbarButton, SceneToolbarInput, SceneVariable, SceneVariableDependencyConfigLike, SceneVariableSet, SceneVariableSetState, SceneVariableState, SceneVariableValueChangedEvent, SceneVariables, TestVariable, TextBoxVariable, UrlSyncManager, ValidateAndUpdateResult, VariableDependencyConfig, VariableValue, VariableValueCustom, VariableValueOption, VariableValueSelectors, VariableValueSingle, VizPanel, VizPanelState, formatRegistry, isSceneObject, sceneGraph };
+interface SceneReactObjectState<TProps = {}> extends SceneLayoutChildState {
+    /**
+     * React component to render
+     */
+    component?: React.ComponentType<TProps>;
+    /**
+     * Props to pass to the component
+     */
+    props?: TProps;
+    /**
+     * Alternative to component and props is just to pass a React node
+     */
+    reactNode?: React.ReactNode;
+}
+/**
+ * A utility object that can be used to render any React component or ReactNode
+ */
+declare class SceneReactObject extends SceneObjectBase<SceneReactObjectState> {
+    static Component: ({ model }: SceneComponentProps<SceneReactObject>) => {} | null;
+}
+
+export { ConstantVariable, CustomFormatterFn, CustomTransformOperator, CustomVariable, DataSourceVariable, DeepPartial, EmbeddedScene, EmbeddedSceneState, FormatRegistryID, FormatVariable, NestedScene, QueryRunnerState, QueryVariable, SceneActivationHandler, SceneApp, SceneAppDrilldownView, SceneAppPage, SceneAppPageLike, SceneAppPageState, SceneAppRoute, SceneByFrameRepeater, SceneCanvasText, SceneComponent, SceneComponentProps, SceneControlsSpacer, SceneDataNode, SceneDataProvider, SceneDataState, SceneDataTransformer, SceneDeactivationHandler, SceneEditor, SceneEditorState, SceneFlexLayout, SceneGridLayout, SceneGridRow, SceneLayout, SceneLayoutChild, SceneLayoutChildOptions, SceneLayoutChildState, SceneLayoutState, SceneObject, SceneObjectBase, SceneObjectRef, SceneObjectState, SceneObjectStateChangedEvent, SceneObjectStateChangedPayload, SceneObjectStatePlain, SceneObjectUrlSyncConfig, SceneObjectUrlSyncHandler, SceneObjectUrlValue, SceneObjectUrlValues, SceneObjectWithUrlSync, SceneQueryRunner, SceneReactObject, SceneRefreshPicker, SceneRouteMatch, SceneStateChangedHandler, SceneTimePicker, SceneTimeRange, SceneTimeRangeLike, SceneTimeRangeState, SceneToolbarButton, SceneToolbarInput, SceneVariable, SceneVariableDependencyConfigLike, SceneVariableSet, SceneVariableSetState, SceneVariableState, SceneVariableValueChangedEvent, SceneVariables, TestVariable, TextBoxVariable, UrlSyncManager, ValidateAndUpdateResult, VariableDependencyConfig, VariableValue, VariableValueCustom, VariableValueOption, VariableValueSelectors, VariableValueSingle, VizPanel, VizPanelMenu, VizPanelState, formatRegistry, isSceneObject, sceneGraph };