Plugin: Plugin Capabilities

[leventebalogh]

Related issue / epic: #77856

What changed?

Plugin Capabilities

This PR introduces something called "plugin capabilities", that can be used as the following (supersedes #83692):

// Register a capability (in the `module.tsx` file inside your plugin.)
// -----------------------

// Registers a function as a capability with the ID: "{YOUR_PLUGIN_ID}/foo"
// (Anything you register will be namespaced by your plugin id. You cannot use "/"s in the id.) 
.configureCapability('foo', {
    title: 'Foo',
    description: 'This is a foo capability',
    function: (name: string) => {
      console.log(`Hello ${name}!`);
    },
})

// Access a capability
// -------------------

// Example 1.
// This will wait until a capability with the ID is added to the registry.
// (Currently there is no timeout set by default.) 
const predict = await getPluginCapability("grafana-ml-app/predict");

// Example 2.
// This one times out in 1000ms if the capability with the ID is still not available 
const predict = await getPluginCapability("grafana-ml-app/predict", { timeout: 1000 });

// Example 3.
// This sets a type for the `fn()` capability function 
const predict = await getPluginCapability<(name: string) => void>("grafana-ml-app/predict", { timeout: 1000 });

// Use the capability
const predictions = predict();


// Function extensions
// ----------------------

.configureExtensionFunction({
    extensionPointId: 'grafana/command-palette'
    title: 'Search for k8s clusters',
    description: 'This extends Grafana search with searching for k8s clusters',
    function: async (query: string) => {
      const clusters = await searchForK8sClusters(query);

      return clusters;
    },
});

const functions = getPluginFunctionExtensions({ extensionPointId: 'grafana/command-palette' });

Todo:

•  Add tests
• Clean up names
• Add an reactive hook

[yduartep]

@leventebalogh what is the difference between this configureExtensionFunction and the existing configureExtensionComponent that is already part of the plugin extension feature? are they similar ways to extend the UI?

[leventebalogh]

Hey @yduartep 👋 Very good question! This PR is still in draft, and the "function extensions" are only an experiment at this point, they might won't land in the end. The reasoning and the difference: although react components can be functions as well (function components), for those extensions we have stricter type restrictions than for ordinary functions. Another difference is that function extensions can be async functions, which can be useful in use cases like for example expecting search results from plugins for a certain query string.

I hope it answered your question - please let me know if it didn't.
We will make sure that they have proper documentation in case they land in our public API.

[yduartep]

Hey @yduartep 👋 Very good question! This PR is still in draft, and the "function extensions" are only an experiment at this point, they might won't land in the end. The reasoning and the difference: although react components can be functions as well (function components), for those extensions we have stricter type restrictions than for ordinary functions. Another difference is that function extensions can be async functions, which can be useful in use cases like for example expecting search results from plugins for a certain query string.

I hope it answered your question - please let me know if it didn't. We will make sure that they have proper documentation in case they land in our public API.

Thank you. Just try to explain very good this on the final documentation and if is possible include some real use cases to help to understand the feature.

[marefr]

Nit. We've been talking about plugin capabilities in a greater scope of what plugins can do/contributes to so maybe a bit confusing naming this "capability"? What about command, ref https://code.visualstudio.com/api/extension-capabilities/common-capabilities#command

[yduartep]

Hi @leventebalogh when do you think this configureCapability will be in prod? I would like to start working with the new functionality that is amazing!!

[leventebalogh]

Hi @yduartep 👋

We are working very hard to get this feature/branch into a final version and merge it by this Friday. We will keep you in the loop :)