@grafana/scenes 8.17.0 → 8.18.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _grafana_schema from '@grafana/schema';
 import { VariableType, VariableHide, LoadingState, TimeZone, DataQuery, DataTopic, DataSourceRef, VariableRefresh, DashboardCursorSync, MatcherConfig, TableFieldOptions } from '@grafana/schema';
 import * as _grafana_data from '@grafana/data';
-import { BusEventWithPayload, EventBus, BusEvent, BusEventType, BusEventHandler, PanelMenuItem, DataQueryRequest, FieldConfigSource, PanelPlugin, AbsoluteTimeRange, PanelData, InterpolateFunction, PanelModel, TimeRange, DataTransformContext, DataFrame, DataSourceGetTagKeysOptions, DataSourceGetTagValuesOptions, IconName, PageLayoutType, UrlQueryMap, DataQuery as DataQuery$1, DataSourceApi, Registry, RegistryItem, ScopedVars, AdHocVariableFilter, SelectableValue, GetTagResponse, MetricFindValue, DrilldownsApplicability, VariableRegexApplyTo, VariableRefresh as VariableRefresh$1, VariableSort, Scope, EventFilterOptions, AnnotationEvent, AnnotationQuery, DataTransformerConfig, TimeOption, FieldConfig, FieldType, FieldValueMatcherConfig, ScopedVar, RawTimeRange } from '@grafana/data';
+import { BusEventWithPayload, EventBus, BusEvent, BusEventType, BusEventHandler, PanelMenuItem, DataQueryRequest, DataFrame, DataTransformerConfig, CustomTransformOperator as CustomTransformOperator$1, FieldConfigSource, PanelPlugin, AbsoluteTimeRange, PanelData, InterpolateFunction, PanelModel, TimeRange, DataTransformContext, DataSourceGetTagKeysOptions, DataSourceGetTagValuesOptions, IconName, PageLayoutType, UrlQueryMap, DataQuery as DataQuery$1, DataSourceApi, Registry, RegistryItem, ScopedVars, AdHocVariableFilter, SelectableValue, GetTagResponse, MetricFindValue, DrilldownsApplicability, VariableRegexApplyTo, VariableRefresh as VariableRefresh$1, VariableSort, Scope, EventFilterOptions, AnnotationEvent, AnnotationQuery, TimeOption, FieldConfig, FieldType, FieldValueMatcherConfig, ScopedVar, RawTimeRange } from '@grafana/data';
 import * as React$1 from 'react';
 import React__default, { ComponentType, CSSProperties, PointerEvent, ForwardRefExoticComponent } from 'react';
 import * as rxjs from 'rxjs';
@@ -444,6 +444,49 @@ declare class VizPanelRenderProfiler extends SceneObjectBase<VizPanelRenderProfi
     }): DataTransformCompletionCallback | null;
 }
 
+/**
+ * Identifies the contributor that injected a system transformation.
+ */
+type TransformationOrigin = string;
+/**
+ * Whether a system transformation runs before or after the user configured transformations.
+ */
+type SystemTransformationPosition = 'prepend' | 'append';
+/**
+ * A provider contributed transformation.
+ */
+type SystemTransformation = (DataTransformerConfig | Exclude<CustomTransformerDefinition, CustomTransformOperator$1>) & {
+    origin: TransformationOrigin;
+    position: SystemTransformationPosition;
+};
+/**
+ * Contributes transformations that wrap the user configured ones.
+ * A SceneDataTransformer discovers on its parent when it activates (e.g. VizPanel).
+ * Nothing a provider contributes ever reaches `state.transformations`.
+ */
+interface SystemTransformationsProvider {
+    readonly isSystemTransformationsProvider: true;
+    readonly origin: TransformationOrigin;
+    /**
+     * Resolves what to run for the frames about to enter the pipeline. Called on every pass and does not write scene state.
+     * Throwing is treated as noop rather than erroring.
+     * What this returns is never interpolated. Only `state.transformations` is scanned for variable dependencies.
+     */
+    getSystemTransformations(ctx: {
+        series: DataFrame[];
+    }): {
+        prepend?: Array<DataTransformerConfig | CustomTransformerDefinition>;
+        append?: Array<DataTransformerConfig | CustomTransformerDefinition>;
+    };
+}
+/**
+ * The system transformations in effect for a given set of source frames, in pipeline order.
+ */
+interface ResolvedSystemTransformations {
+    prepend: SystemTransformation[];
+    append: SystemTransformation[];
+}
+
 interface VizPanelState<TOptions = {}, TFieldConfig = {}> extends SceneObjectState {
     /**
      * This is usually a plugin id that references a core plugin or an external plugin. But this can also reference a
@@ -505,6 +548,10 @@ interface VizPanelState<TOptions = {}, TFieldConfig = {}> extends SceneObjectSta
      * see https://github.com/grafana/grafana/pull/120190
      **/
     _UNSAFE_clearPreviousFieldValues?: boolean;
+    /**
+     * Whether to check the panel plugin for system transformations. Set by host to gate rollout (feature toggle)
+     */
+    applyPluginTransformations?: boolean;
     /**
      * Sets panel chrome collapsed state
      */
@@ -523,11 +570,17 @@ interface VizPanelState<TOptions = {}, TFieldConfig = {}> extends SceneObjectSta
     _pluginInstanceState?: any;
     _renderCounter?: number;
 }
-declare class VizPanel<TOptions = {}, TFieldConfig extends {} = {}> extends SceneObjectBase<VizPanelState<TOptions, TFieldConfig>> {
+declare class VizPanel<TOptions = {}, TFieldConfig extends {} = {}> extends SceneObjectBase<VizPanelState<TOptions, TFieldConfig>> implements SystemTransformationsProvider {
     static Component: typeof VizPanelRenderer;
     protected _variableDependency: VariableDependencyConfig<VizPanelState<{}, {}>>;
     protected _panelContext?: PanelContext;
+    /**
+     * The plugin this panel has adopted: options have been migrated and defaulted against it, so it
+     * deliberately lags state.pluginId while a viz type change is still loading.
+     */
     private _plugin?;
+    /** The in-flight import, so concurrent callers share one. */
+    private _pluginImport?;
     private _prevData?;
     private _dataWithFieldConfig?;
     private _structureRev;
@@ -539,6 +592,11 @@ declare class VizPanel<TOptions = {}, TFieldConfig extends {} = {}> extends Scen
     private _onActivate;
     forceRender(): void;
     private _loadPlugin;
+    /**
+     * The only place the plugin is imported. Concurrent callers (_loadPlugin, getPluginAsync) share one import,
+     * and a rejection stays cached so a plugin that fails to load is not retried on every call.
+     */
+    private _importPlugin;
     getLegacyPanelId(): number;
     /**
      * Unique id string that includes local variable values (for repeated panels)
@@ -546,7 +604,48 @@ declare class VizPanel<TOptions = {}, TFieldConfig extends {} = {}> extends Scen
     getPathId(): string;
     private _pluginLoaded;
     private _getPluginVersion;
+    /**
+     * The plugin this panel has adopted, or undefined while it is still loading.
+     */
     getPlugin(): PanelPlugin | undefined;
+    /**
+     * The plugin for the current state.pluginId, importing it if it is not loaded yet. Rejects when
+     * the import does, like the host's importPanelPlugin.
+     *
+     * Unlike getPlugin this does not return undefined merely because the import has not finished, and
+     * it does not wait on the panel being activated. It does not adopt what it resolves: option
+     * migrations and the state write stay with _loadPlugin, on the render and viz change paths.
+     */
+    getPluginAsync(): Promise<PanelPlugin>;
+    /**
+     * The plugin for the current state.pluginId when it is available without importing: the one this
+     * panel adopted, or one already in the host's cache.
+     */
+    private _resolvePluginSync;
+    /**
+     * @internal
+     * Marks this panel as a SystemTransformationsProvider; not for app code.
+     */
+    readonly isSystemTransformationsProvider: true;
+    /**
+     * @internal
+     * Identifies this panel's tier in its data pipeline; not for app code.
+     */
+    readonly origin: TransformationOrigin;
+    /**
+     * @internal
+     * Called by the SceneDataTransformer that discovered this panel with the frames about to enter the pipeline.
+     */
+    getSystemTransformations({ series }: {
+        series: DataFrame[];
+    }): {
+        prepend?: Array<DataTransformerConfig | CustomTransformerDefinition>;
+        append?: Array<DataTransformerConfig | CustomTransformerDefinition>;
+    };
+    /**
+     * The plugin that contributes the transformations for this panel.
+     */
+    private _pluginForTransformations;
     getPanelContext(): PanelContext;
     onTimeRangeChange: (timeRange: AbsoluteTimeRange) => void;
     getTimeRange: (data?: PanelData) => _grafana_data.TimeRange;
@@ -2481,7 +2580,8 @@ declare function SceneDataLayerControlsRenderer({ model }: SceneComponentProps<S
 
 interface SceneDataTransformerState extends SceneDataState {
     /**
-     * Array of standard transformation configs and custom transform operators
+     * Array of standard transformation configs and custom transform operators.
+     * User configured only: system contributed transformations provided by getResolvedSystemTransformations.
      */
     transformations: Array<DataTransformerConfig | CustomTransformerDefinition>;
 }
@@ -2497,16 +2597,81 @@ declare class SceneDataTransformer extends SceneObjectBase<SceneDataTransformerS
     private _transformSub?;
     private _results;
     private _prevDataFromSource?;
+    /**
+     * The provider found on the parent. Kept across deactivation rather than cleared with the subscription:
+     * the transformations editor reads getResolvedSystemTransformations for panels that are not currently
+     * rendering, and re-discovering on the next activation would be too late. Re-derived from the parent on
+     * every activation, so it does not survive a move to a tree whose parent contributes nothing.
+     */
+    private _provider?;
+    /**
+     * One slot memo so that a pass resolves the provider once and the editors reading
+     * getResolvedSystemTransformations see what the pipeline used rather than re-resolving.
+     */
+    private _resolvedSystem?;
+    /**
+     * Whether a previous activation already ran a pass, which is what makes the provider found on this one a
+     * *change* rather than a first discovery. Not carried over by clone, unlike `_prevDataFromSource`.
+     */
+    private _hasActivatedBefore;
+    /**
+     * The system transformations that produced the current `state.data`, as opposed to what resolves now.
+     * Written only where `_prevDataFromSource` is, so the two always describe the same pass: a pass
+     * cancelled by deactivation has applied neither, and must not be taken for one that landed.
+     */
+    private _lastPassSystem?;
     /**
      * Scan transformations for variable usage and re-process transforms when a variable values change
      */
     protected _variableDependency: VariableDependencyConfig<SceneDataTransformerState>;
     constructor(state: SceneDataTransformerState);
     private activationHandler;
+    /**
+     * Checks the parent for system transformation provider.
+     * Reports whether what the pipeline should run has changed since the last pass, so the caller can force one.
+     */
+    private _discoverProvider;
+    /**
+     * Whether the provider resolves to something other than what the last pass ran.
+     *
+     * The provider instance being unchanged is not enough to conclude the pipeline is unchanged: nothing
+     * was watching while this was inactive, so a plugin that finished importing in that window resolves
+     * differently now. Source frames usually survive a re-activation unchanged, so without this the pass
+     * is skipped as already transformed and state.data keeps frames the reported pipeline never produced.
+     */
+    private _systemChangedSinceLastPass;
     private getSourceData;
     setContainerWidth(width: number): void;
     isDataReadyToDisplay(): boolean;
+    /**
+     * @internal
+     * Whether the pass behind the current state.data applied any system transformations. A provider that has
+     * stopped contributing still needs one more pass to take them back out.
+     */
+    hasAppliedSystemTransformations(): boolean;
     reprocessTransformations(): void;
+    /**
+     * The system transformations for the given source frames.
+     * Public because provider output never reaches state, so this is the only way for readers
+     * (the transformations editor, the inspect data tab) to see what the pipeline is running.
+     */
+    getResolvedSystemTransformations(series?: DataFrame[]): ResolvedSystemTransformations;
+    /**
+     * The source frames to resolve a provider against when the caller did not supply their own.
+     *
+     * Mirrors getSourceData's precondition: reading what is running must not throw for a transformer that is not wired.
+     * Since every VizPanel is a provider, a panel without `$data` would throw.
+     */
+    private _sourceSeriesOrNone;
+    private _resolveProvider;
+    /**
+     * The system transformations to run for the given source frames.
+     */
+    private _systemTransformationsFor;
+    /**
+     * Places the user configured transformations between the system tiers, in prepend, user, append order.
+     */
+    private _withSystemTransformations;
     /**
      * S3.1: Calculate transformation complexity metrics
      */
@@ -3927,6 +4092,11 @@ declare const timeShiftAlignmentProcessor: ExtraQueryDataProcessor;
  */
 declare const loadResources: ResourceLoader;
 
+/**
+ * Narrows SystemTransformationsProvider
+ */
+declare function isSystemTransformationsProvider(o: unknown): o is SystemTransformationsProvider;
+
 
 
 
@@ -3988,5 +4158,10 @@ declare const sceneUtils: {
     buildPathIdFor: typeof buildPathIdFor;
 };
 
-export { AdHocFiltersComboboxRenderer, AdHocFiltersVariable, AdHocFiltersVariableController, ConstantVariable, ControlsLabel, CustomVariable, DataProviderProxy, DataSourceVariable, EmbeddedScene, FieldConfigBuilder, FieldConfigBuilders, FieldConfigOverridesBuilder, GRID_CELL_HEIGHT, GRID_COLUMN_COUNT, GROUP_BY_OPERATOR, GroupByVariable, IntervalVariable, LazyLoader, LocalValueVariable, MultiOrSingleValueSelect, MultiValueVariable, NestedScene, NewSceneObjectAddedEvent, OPERATORS, PATH_ID_SEPARATOR, PanelBuilders, PanelOptionsBuilders, QueryVariable, RuntimeDataSource, SafeSerializableSceneObject, SceneApp, SceneAppPage, SceneByFrameRepeater, SceneByVariableRepeater, SceneCSSGridItem, SceneCSSGridLayout, SceneCanvasText, SceneControlsSpacer, SceneDataLayerBase, SceneDataLayerControls, SceneDataLayerSet, SceneDataLayerSetBase, SceneDataNode, SceneDataTransformer, SceneDebugger, SceneFlexItem, SceneFlexLayout, SceneGridItem, SceneGridLayout, SceneGridLayoutDragStartEvent, SceneGridRow, SceneObjectBase, SceneObjectRef, SceneObjectRemovedEvent, SceneObjectStateChangedEvent, SceneObjectUrlSyncConfig, SceneQueryRunner, SceneReactObject, SceneRefreshPicker, SceneTimePicker, SceneTimeRange, SceneTimeRangeCompare, SceneTimeRangeTransformerBase, SceneTimeZoneOverride, SceneToolbarButton, SceneToolbarInput, SceneVariableSet, SceneVariableValueChangedEvent, ScopesVariable, SplitLayout, SwitchVariable, TestVariable, TextBoxVariable, UrlSyncContextProvider, UrlSyncManager, UserActionEvent, VariableDependencyConfig, VariableValueControl, VariableValueSelectWrapper, VariableValueSelectors, VizConfigBuilder, VizConfigBuilders, VizPanel, VizPanelBuilder, VizPanelExploreButton, VizPanelFitScope, VizPanelMenu, index$2 as behaviors, index as dataLayers, escapeUrlPipeDelimiters, formatRegistry, getClosest, getCompareSeriesRefId, getExploreURL, getQueriesForVariables, isCustomVariableValue, isDataLayer, isDataRequestEnricher, isFiltersRequestEnricher, isGroupByFilter, isSceneObject, loadResources, index$1 as performanceUtils, registerQueryWithController, registerRuntimeDataSource, sceneGraph, sceneUtils, timeShiftAlignmentProcessor, useSceneApp, useSceneObjectState, useUrlSync, writePerformanceLog };
-export type { AdHocFilterInteractionHandler, AdHocFilterWithLabels, AdHocFiltersController, AdHocFiltersControllerState, CancelActivationHandler, ControlSourceRef, ControlsLayout, CustomFormatterVariable, CustomTransformOperator, CustomTransformerDefinition, CustomVariableValue, DataLayerFilter, DataRequestEnricher, DataSourceControlRef, DeepPartial, EmbeddedSceneState, ExtraQueryDataProcessor, ExtraQueryDescriptor, ExtraQueryProvider, FiltersRequestEnricher, FormatVariable, InterpolationFormatParameter, LazyLoaderMode, MacroVariableConstructor, MultiValueVariableState, OperatorDefinition, QueryRunnerState, SceneActivationHandler, SceneAppDrilldownView, SceneAppPageLike, SceneAppPageState, SceneAppRoute, SceneComponent, SceneComponentProps, SceneDataLayerProvider, SceneDataLayerProviderState, SceneDataProvider, SceneDataProviderResult, SceneDataQuery, SceneDataState, SceneDataTransformerState, SceneDeactivationHandler, SceneFlexItemLike, SceneFlexItemPlacement, SceneFlexItemState, SceneGridItemLike, SceneGridItemStateLike, SceneLayout, SceneLayoutChildOptions, SceneLayoutState, SceneObject, SceneObjectState, SceneObjectStateChangedPayload, SceneObjectUrlSyncHandler, SceneObjectUrlValue, SceneObjectUrlValues, SceneObjectWithUrlSync, SceneQueryControllerEntry, SceneQueryControllerEntryType, SceneQueryControllerLike, SceneRefreshPickerState, SceneRouteMatch, SceneStateChangedHandler, SceneStatelessBehavior, SceneTimeRangeLike, SceneTimeRangeState, SceneUrlSyncOptions, SceneVariable, SceneVariableDependencyConfigLike, SceneVariableSetState, SceneVariableState, SceneVariables, UrlSyncManagerLike, UseStateHookOptions, ValidateAndUpdateResult, VariableCustomFormatterFn, VariableGetOptionsArgs, VariableValue, VariableValueOption, VariableValueOptionProperties, VariableValueSingle, VizConfig, VizPanelFitScopeProps, VizPanelState };
+
+
+
+
+
+export { AdHocFiltersComboboxRenderer, AdHocFiltersVariable, AdHocFiltersVariableController, ConstantVariable, ControlsLabel, CustomVariable, DataProviderProxy, DataSourceVariable, EmbeddedScene, FieldConfigBuilder, FieldConfigBuilders, FieldConfigOverridesBuilder, GRID_CELL_HEIGHT, GRID_COLUMN_COUNT, GROUP_BY_OPERATOR, GroupByVariable, IntervalVariable, LazyLoader, LocalValueVariable, MultiOrSingleValueSelect, MultiValueVariable, NestedScene, NewSceneObjectAddedEvent, OPERATORS, PATH_ID_SEPARATOR, PanelBuilders, PanelOptionsBuilders, QueryVariable, RuntimeDataSource, SafeSerializableSceneObject, SceneApp, SceneAppPage, SceneByFrameRepeater, SceneByVariableRepeater, SceneCSSGridItem, SceneCSSGridLayout, SceneCanvasText, SceneControlsSpacer, SceneDataLayerBase, SceneDataLayerControls, SceneDataLayerSet, SceneDataLayerSetBase, SceneDataNode, SceneDataTransformer, SceneDebugger, SceneFlexItem, SceneFlexLayout, SceneGridItem, SceneGridLayout, SceneGridLayoutDragStartEvent, SceneGridRow, SceneObjectBase, SceneObjectRef, SceneObjectRemovedEvent, SceneObjectStateChangedEvent, SceneObjectUrlSyncConfig, SceneQueryRunner, SceneReactObject, SceneRefreshPicker, SceneTimePicker, SceneTimeRange, SceneTimeRangeCompare, SceneTimeRangeTransformerBase, SceneTimeZoneOverride, SceneToolbarButton, SceneToolbarInput, SceneVariableSet, SceneVariableValueChangedEvent, ScopesVariable, SplitLayout, SwitchVariable, TestVariable, TextBoxVariable, UrlSyncContextProvider, UrlSyncManager, UserActionEvent, VariableDependencyConfig, VariableValueControl, VariableValueSelectWrapper, VariableValueSelectors, VizConfigBuilder, VizConfigBuilders, VizPanel, VizPanelBuilder, VizPanelExploreButton, VizPanelFitScope, VizPanelMenu, index$2 as behaviors, index as dataLayers, escapeUrlPipeDelimiters, formatRegistry, getClosest, getCompareSeriesRefId, getExploreURL, getQueriesForVariables, isCustomVariableValue, isDataLayer, isDataRequestEnricher, isFiltersRequestEnricher, isGroupByFilter, isSceneObject, isSystemTransformationsProvider, loadResources, index$1 as performanceUtils, registerQueryWithController, registerRuntimeDataSource, sceneGraph, sceneUtils, timeShiftAlignmentProcessor, useSceneApp, useSceneObjectState, useUrlSync, writePerformanceLog };
+export type { AdHocFilterInteractionHandler, AdHocFilterWithLabels, AdHocFiltersController, AdHocFiltersControllerState, CancelActivationHandler, ControlSourceRef, ControlsLayout, CustomFormatterVariable, CustomTransformOperator, CustomTransformerDefinition, CustomVariableValue, DataLayerFilter, DataRequestEnricher, DataSourceControlRef, DeepPartial, EmbeddedSceneState, ExtraQueryDataProcessor, ExtraQueryDescriptor, ExtraQueryProvider, FiltersRequestEnricher, FormatVariable, InterpolationFormatParameter, LazyLoaderMode, MacroVariableConstructor, MultiValueVariableState, OperatorDefinition, QueryRunnerState, ResolvedSystemTransformations, SceneActivationHandler, SceneAppDrilldownView, SceneAppPageLike, SceneAppPageState, SceneAppRoute, SceneComponent, SceneComponentProps, SceneDataLayerProvider, SceneDataLayerProviderState, SceneDataProvider, SceneDataProviderResult, SceneDataQuery, SceneDataState, SceneDataTransformerState, SceneDeactivationHandler, SceneFlexItemLike, SceneFlexItemPlacement, SceneFlexItemState, SceneGridItemLike, SceneGridItemStateLike, SceneLayout, SceneLayoutChildOptions, SceneLayoutState, SceneObject, SceneObjectState, SceneObjectStateChangedPayload, SceneObjectUrlSyncHandler, SceneObjectUrlValue, SceneObjectUrlValues, SceneObjectWithUrlSync, SceneQueryControllerEntry, SceneQueryControllerEntryType, SceneQueryControllerLike, SceneRefreshPickerState, SceneRouteMatch, SceneStateChangedHandler, SceneStatelessBehavior, SceneTimeRangeLike, SceneTimeRangeState, SceneUrlSyncOptions, SceneVariable, SceneVariableDependencyConfigLike, SceneVariableSetState, SceneVariableState, SceneVariables, SystemTransformation, SystemTransformationPosition, SystemTransformationsProvider, TransformationOrigin, UrlSyncManagerLike, UseStateHookOptions, ValidateAndUpdateResult, VariableCustomFormatterFn, VariableGetOptionsArgs, VariableValue, VariableValueOption, VariableValueOptionProperties, VariableValueSingle, VizConfig, VizPanelFitScopeProps, VizPanelState };