Plugins: Extend panel menu with commands from plugins (#63802)

* feat(plugins): introduce dashboard panel menu placement for adding menu items

* test: add test for getPanelMenu()

* added an unique identifier for each extension.

* added context to getPluginExtensions.

* wip

* Wip

* wiwip

* Wip

* feat: WWWIIIIPPPP 🧨

* Wip

* Renamed some of the types to align a bit better.

* added limit to how many extensions a plugin can register per placement.

* decreased number of items to 2

* will trim the lenght of titles to max 25 chars.

* wrapping configure function with error handling.

* added error handling for all scenarios.

* moved extension menu items to the bottom of the more sub menu.

* added tests for configuring the title.

* minor refactorings.

* changed so you need to specify the full path in package.json.

* wip

* removed unused type.

* big refactor to make things simpler and to centralize all configure error/validation handling.

* added missing import.

* fixed failing tests.

* fixed tests.

* revert(extensions): remove static extensions config in favour of registering via AppPlugin APIs

* removed the compose that didn't work for some reason.

* added tests just to verify that validation and error handling is tied together in configuration function.

* adding some more values to the context.

* draft validation.

* added missing tests for getPanelMenu.

* added more tests.

* refactor(extensions): move logic for validating extension link config to function

* Fixed ts errors.

* Started to add structure for supporting commands.

* fixed tests.

* adding commands to the registry

* tests: group test cases in describe blocks

* tests: add a little bit more refactoring to the tests

* tests: add a test case for checking correct placements

* feat: first version of the command handler

* feat: register panel menu items with commands

* refactor: make the 'configure' function not optional on `PluginExtensionRegistryItem`

* Wip

* Wip

* Wip

* added test to verify the default configure function.

* added some more tests to verify that commands have the proper error handling for its configure function.

* tests: fix TS errors in tests

* tests: add auxiliary functions

* refactor: small refactoring in tests

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* refactor: refactoring tests for registryFactory

* draft of wrapping command handler with error handling.

* refactor: refactoring tests for registryFactory

* added test for edge case.

* replaced the registry item with a configure function.

* renamed the configure function type.

* refactoring of the registryfactory.

* added tests for handler error handling.

* fixed issue with assert function.

* added comment about the limited type.

* Update public/app/features/plugins/extensions/errorHandling.test.ts

Co-authored-by: Levente Balogh <balogh.levente.hu@gmail.com>

* Update public/app/features/plugins/extensions/errorHandling.test.ts

Co-authored-by: Levente Balogh <balogh.levente.hu@gmail.com>

* Update public/app/features/plugins/extensions/errorHandling.test.ts

Co-authored-by: Levente Balogh <balogh.levente.hu@gmail.com>

* added missing tests.

---------

Co-authored-by: Jack Westbrook <jack.westbrook@gmail.com>
Co-authored-by: Levente Balogh <balogh.levente.hu@gmail.com>

packages/grafana-data/src/types/app.ts

@@ -3,7 +3,7 @@ import { ComponentType } from 'react';
 import { KeyValue } from './data';
 import { NavModel } from './navModel';
 import { PluginMeta, GrafanaPlugin, PluginIncludeType } from './plugin';
-import { extensionLinkConfigIsValid, PluginExtensionLink } from './pluginExtensions';
+import { extensionLinkConfigIsValid, type PluginExtensionCommand, type PluginExtensionLink } from './pluginExtensions';
 
 /**
  * @public
@@ -51,23 +51,32 @@ export interface AppPluginMeta<T extends KeyValue = KeyValue> extends PluginMeta
 }
 
 /**
- * These types are towards the plugin developer when extending Grafana or other
- * plugins from the module.ts
+ * The `configure()` function can only update certain properties of the extension, and due to this
+ * it only receives a subset of the original extension object.
  */
-export type AppConfigureExtension<T, C = object> = (extension: T, context: C) => Partial<T> | undefined;
-
 export type AppPluginExtensionLink = Pick<PluginExtensionLink, 'description' | 'path' | 'title'>;
 
+export type AppPluginExtensionCommand = Pick<PluginExtensionCommand, 'description' | 'title'>;
+
 export type AppPluginExtensionLinkConfig<C extends object = object> = {
   title: string;
   description: string;
   placement: string;
   path: string;
-  configure?: AppConfigureExtension<AppPluginExtensionLink, C>;
+  configure?: (extension: AppPluginExtensionLink, context?: C) => Partial<AppPluginExtensionLink> | undefined;
+};
+
+export type AppPluginExtensionCommandConfig<C extends object = object> = {
+  title: string;
+  description: string;
+  placement: string;
+  handler: (context?: C) => void;
+  configure?: (extension: AppPluginExtensionCommand, context?: C) => Partial<AppPluginExtensionCommand> | undefined;
 };
 
 export class AppPlugin<T extends KeyValue = KeyValue> extends GrafanaPlugin<AppPluginMeta<T>> {
   private linkExtensions: AppPluginExtensionLinkConfig[] = [];
+  private commandExtensions: AppPluginExtensionCommandConfig[] = [];
 
   // Content under: /a/${plugin-id}/*
   root?: ComponentType<AppRootProps<T>>;
@@ -113,6 +122,10 @@ export class AppPlugin<T extends KeyValue = KeyValue> extends GrafanaPlugin<AppP
     return this.linkExtensions;
   }
 
+  get extensionCommands(): AppPluginExtensionCommandConfig[] {
+    return this.commandExtensions;
+  }
+
   configureExtensionLink<C extends object>(config: AppPluginExtensionLinkConfig<C>) {
     const { path, description, title, placement } = config;
 
@@ -124,6 +137,11 @@ export class AppPlugin<T extends KeyValue = KeyValue> extends GrafanaPlugin<AppP
     this.linkExtensions.push(config as AppPluginExtensionLinkConfig);
     return this;
   }
+
+  configureExtensionCommand<C extends object>(config: AppPluginExtensionCommandConfig<C>) {
+    this.commandExtensions.push(config as AppPluginExtensionCommandConfig);
+    return this;
+  }
 }
 
 /**

packages/grafana-data/src/types/index.ts

@@ -56,5 +56,9 @@ export {
   type PluginExtension,
   type PluginExtensionLink,
   isPluginExtensionLink,
+  assertPluginExtensionLink,
+  type PluginExtensionCommand,
+  isPluginExtensionCommand,
+  assertPluginExtensionCommand,
   PluginExtensionTypes,
 } from './pluginExtensions';

packages/grafana-data/src/types/pluginExtensions.ts

@@ -4,6 +4,7 @@
 
 export enum PluginExtensionTypes {
   link = 'link',
+  command = 'command',
 }
 
 export type PluginExtension = {
@@ -18,10 +19,41 @@ export type PluginExtensionLink = PluginExtension & {
   path: string;
 };
 
-export function isPluginExtensionLink(extension: PluginExtension): extension is PluginExtensionLink {
+export type PluginExtensionCommand = PluginExtension & {
+  type: PluginExtensionTypes.command;
+  callHandlerWithContext: () => void;
+};
+
+export function isPluginExtensionLink(extension: PluginExtension | undefined): extension is PluginExtensionLink {
+  if (!extension) {
+    return false;
+  }
   return extension.type === PluginExtensionTypes.link && 'path' in extension;
 }
 
+export function assertPluginExtensionLink(
+  extension: PluginExtension | undefined
+): asserts extension is PluginExtensionLink {
+  if (!isPluginExtensionLink(extension)) {
+    throw new Error(`extension is not a link extension`);
+  }
+}
+
+export function isPluginExtensionCommand(extension: PluginExtension | undefined): extension is PluginExtensionCommand {
+  if (!extension) {
+    return false;
+  }
+  return extension.type === PluginExtensionTypes.command;
+}
+
+export function assertPluginExtensionCommand(
+  extension: PluginExtension | undefined
+): asserts extension is PluginExtensionCommand {
+  if (!isPluginExtensionCommand(extension)) {
+    throw new Error(`extension is not a command extension`);
+  }
+}
+
 export function extensionLinkConfigIsValid(props: {
   path?: string;
   description?: string;