[SIG-55948] Plugin Actions Support: Added custom hook for action regi…

…stration and triggering (#10)

Co-authored-by: Alison Lai <[email protected]>

README.md

@@ -247,6 +247,11 @@ type CustomPluginConfigOptions =
       type: 'interaction';
       name: string;
       label?: string;
+    }
+  | {
+      type: 'action-trigger';
+      name: string;
+      label?: string;
     };
 ```
 
@@ -376,6 +381,10 @@ Additional Fields
 
 A configurable workbook interaction to interact with other charts within your workbook
 
+**Action Trigger**
+
+A configurable action trigger to trigger actions in other elements within your workbook
+
 #### PluginInstance
 
 ```ts
@@ -437,6 +446,11 @@ interface PluginInstance<T> {
       selection: WorkbookSelection[],
     ): void;
 
+    /**
+     * Triggers an action based on the provided action trigger Id
+     */
+    triggerAction(id: string): void;
+
     /**
      * Overrider function for Config Ready state
      */
@@ -677,6 +691,24 @@ The returned setter function accepts an array of workbook selection elements
 function setVariableCallback(value: WorkbookSelection[]): void;
 ```
 
+#### useActionTrigger()
+
+Returns a callback function to trigger one or more action effects for a given action trigger
+
+```ts
+function useActionTrigger(triggerId: string);
+```
+
+Arguments
+
+- `triggerId : string` - The ID of the action trigger
+
+The function that can be called to trigger the action
+
+```ts
+function triggerActionCallback(): void;
+```
+
 #### useConfig()
 
 Returns the workbook element’s current configuration. If a key is provided, only

src/client/initialize.ts

@@ -14,6 +14,7 @@ export function initialize<T = {}>(): PluginInstance<T> {
 
   let subscribedInteractions: Record<string, WorkbookSelection[]> = {};
   let subscribedWorkbookVars: Record<string, WorkbookVariable> = {};
+  const registeredActionTriggers = new Set<string>();
 
   const listeners: {
     [event: string]: Function[];
@@ -135,7 +136,18 @@ export function initialize<T = {}>(): PluginInstance<T> {
       ) {
         void execPromise('wb:plugin:selection:set', id, elementId, selection);
       },
+      triggerAction(id: string) {
+        if (!registeredActionTriggers.has(id)) {
+          throw new Error(`Invalid action trigger ID: ${id}`);
+        }
+        void execPromise('wb:plugin:action-trigger:invoke', id);
+      },
       configureEditorPanel(options) {
+        registeredActionTriggers.clear();
+        for (const option of options) {
+          if (option.type !== 'action-trigger') continue;
+          registeredActionTriggers.add(option.name);
+        }
         void execPromise('wb:plugin:config:inspector', options);
       },
       setLoadingState(loadingState) {

src/react/hooks.ts

@@ -176,3 +176,17 @@ export function useInteraction(
 
   return [workbookInteraction, setInteraction];
 }
+
+/**
+ * React hook for returning a triggering callback function for the registered
+ * action trigger
+ * @param {string} id ID of action trigger
+ * @returns {Function} A callback function to trigger the action
+ */
+export function useActionTrigger(id: string) {
+  const client = usePlugin();
+
+  return useCallback(() => {
+    client.config.triggerAction(id);
+  }, [client, id]);
+}

src/types.ts

@@ -166,6 +166,11 @@ export type CustomPluginConfigOptions =
       type: 'interaction';
       name: string;
       label?: string;
+    }
+  | {
+      type: 'action-trigger';
+      name: string;
+      label?: string;
     };
 
 /**
@@ -255,6 +260,12 @@ export interface PluginInstance<T = any> {
       selection: WorkbookSelection[],
     ): void;
 
+    /**
+     * Triggers an action based on the provided action trigger Id
+     * @param {string} id ID from action-trigger type in Plugin Config
+     */
+    triggerAction(id: string): void;
+
     /**
      * Overrider function for Config Ready state
      * @param {boolean} loadingState Boolean representing if Plugin Config is still loading