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;

packages/grafana-runtime/src/services/index.ts

@@ -11,7 +11,6 @@ export * from './appEvents';
 export {
   type PluginExtensionRegistry,
   type PluginExtensionRegistryItem,
-  type RegistryConfigureExtension,
   setPluginsExtensionRegistry,
 } from './pluginExtensions/registry';
 export {

packages/grafana-runtime/src/services/pluginExtensions/extensions.test.ts

@@ -1,4 +1,4 @@
-import { isPluginExtensionLink, PluginExtension, PluginExtensionLink, PluginExtensionTypes } from '@grafana/data';
+import { assertPluginExtensionLink, PluginExtensionLink, PluginExtensionTypes } from '@grafana/data';
 
 import { getPluginExtensions } from './extensions';
 import { PluginExtensionRegistryItem, setPluginsExtensionRegistry } from './registry';
@@ -33,7 +33,7 @@ describe('getPluginExtensions', () => {
       const { extensions } = getPluginExtensions({ placement });
       const [extension] = extensions;
 
-      assertLinkExtension(extension);
+      assertPluginExtensionLink(extension);
 
       expect(extension.path).toBe(`/a/${pluginId}/declare-incident`);
       expect(extensions.length).toBe(1);
@@ -43,7 +43,7 @@ describe('getPluginExtensions', () => {
       const { extensions } = getPluginExtensions({ placement });
       const [extension] = extensions;
 
-      assertLinkExtension(extension);
+      assertPluginExtensionLink(extension);
 
       expect(extension.description).toBe('Declaring an incident in the app');
       expect(extensions.length).toBe(1);
@@ -53,13 +53,13 @@ describe('getPluginExtensions', () => {
       const { extensions } = getPluginExtensions({ placement });
       const [extension] = extensions;
 
-      assertLinkExtension(extension);
+      assertPluginExtensionLink(extension);
 
       expect(extension.title).toBe('Declare incident');
       expect(extensions.length).toBe(1);
     });
 
-    it('should return an empty array when extensions cannot be found', () => {
+    it('should return an empty array when extensions can be found', () => {
       const { extensions } = getPluginExtensions({
         placement: 'plugins/not-installed-app/news',
       });
@@ -72,17 +72,8 @@ describe('getPluginExtensions', () => {
 function createRegistryLinkItem(
   link: Omit<PluginExtensionLink, 'type'>
 ): PluginExtensionRegistryItem<PluginExtensionLink> {
-  return {
-    configure: undefined,
-    extension: {
-      ...link,
-      type: PluginExtensionTypes.link,
-    },
-  };
-}
-
-function assertLinkExtension(extension: PluginExtension): asserts extension is PluginExtensionLink {
-  if (!isPluginExtensionLink(extension)) {
-    throw new Error(`extension is not a link extension`);
-  }
+  return (context?: object) => ({
+    ...link,
+    type: PluginExtensionTypes.link,
+  });
 }

packages/grafana-runtime/src/services/pluginExtensions/extensions.ts

@@ -16,15 +16,10 @@ export function getPluginExtensions<T extends object = {}>(
 ): PluginExtensionsResult {
   const { placement, context } = options;
   const registry = getPluginsExtensionRegistry();
-  const items = registry[placement] ?? [];
+  const configureFuncs = registry[placement] ?? [];
 
-  const extensions = items.reduce<PluginExtension[]>((result, item) => {
-    if (!context || !item.configure) {
-      result.push(item.extension);
-      return result;
-    }
-
-    const extension = item.configure(context);
+  const extensions = configureFuncs.reduce<PluginExtension[]>((result, configure) => {
+    const extension = configure(context);
     if (extension) {
       result.push(extension);
     }

packages/grafana-runtime/src/services/pluginExtensions/registry.ts

@@ -1,14 +1,9 @@
 import { PluginExtension } from '@grafana/data';
 
-export type RegistryConfigureExtension<T extends PluginExtension = PluginExtension, C extends object = object> = (
-  context: C
+export type PluginExtensionRegistryItem<T extends PluginExtension = PluginExtension, C extends object = object> = (
+  context?: C
 ) => T | undefined;
 
-export type PluginExtensionRegistryItem<T extends PluginExtension = PluginExtension, C extends object = object> = {
-  extension: T;
-  configure?: RegistryConfigureExtension<T, C>;
-};
-
 export type PluginExtensionRegistry = Record<string, PluginExtensionRegistryItem[]>;
 
 let registry: PluginExtensionRegistry | undefined;