Add support for Actions within plugins (#17)

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

Author: 3 people

README.md

@@ -159,8 +159,8 @@ Before you start:
 #### CustomPluginConfigOptions
 
 A plugin can be configured with any number of configuration fields. Each field
-type has its own configuration options. Each field type is also garunteed to
-have a the following options:
+type has its own configuration options. Each field type is also guaranteed to
+have the following options:
 
 - `name : string` - the name of the field
 - `type : string` - the field type
@@ -247,6 +247,16 @@ type CustomPluginConfigOptions =
       type: 'interaction';
       name: string;
       label?: string;
+    }
+  | {
+      type: 'action-trigger';
+      name: string;
+      label?: string;
+    }
+  | {
+      type: 'action-effect';
+      name: string;
+      label?: string;
     };
 ```
 
@@ -376,6 +386,14 @@ 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
+
+**Action Effect**
+
+A configurable action effect that can be triggered by other elements within your workbook
+
 #### PluginInstance
 
 ```ts
@@ -437,6 +455,16 @@ interface PluginInstance<T> {
       selection: WorkbookSelection[],
     ): void;
 
+    /**
+     * Triggers an action based on the provided action trigger ID
+     */
+    triggerAction(id: string): void;
+
+    /**
+     * Registers an effect with the provided action effect ID
+     */
+    registerEffect(id: string, effect: Function): void;
+
     /**
      * Overrider function for Config Ready state
      */
@@ -678,7 +706,7 @@ function setVariableCallback(...values: unknown[]): void;
 
 #### useInteraction()
 
-Returns a given interaction's selection state and a setter to update that interation
+Returns a given interaction's selection state and a setter to update that interaction
 
 ```ts
 function useInteraction(
@@ -699,6 +727,41 @@ The returned setter function accepts an array of workbook selection elements
 function setVariableCallback(value: WorkbookSelection[]): void;
 ```
 
+#### useActionTrigger()
+
+- `configId : string` - The ID of the action trigger from the Plugin Config
+
+Returns a callback function to trigger one or more action effects for a given action trigger
+
+```ts
+function useActionTrigger(configId: string): () => void;
+```
+
+#### triggerActionCallback();
+
+Arguments
+
+- `configId : string` - The ID of the action trigger from the Plugin Config
+
+The function that can be called to asynchronously trigger the action
+
+```ts
+function triggerActionCallback(configId: string): void;
+```
+
+#### useActionEffect()
+
+Registers and unregisters an action effect within the plugin
+
+```ts
+function useActionEffect(effectId: string, effect: () => void);
+```
+
+Arguments
+
+- `effectId : string` - The ID of the action effect
+- `effect : Function` - The function to be called when the effect is triggered
+
 #### 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 registeredEffects: Record<string, () => void> = {};
 
   const listeners: {
     [event: string]: Function[];
@@ -59,6 +60,14 @@ export function initialize<T = {}>(): PluginInstance<T> {
     Object.assign(subscribedInteractions, updatedInteractions);
   });
 
+  on('wb:plugin:action-effect:invoke', (configId: string) => {
+    const effect = registeredEffects[configId];
+    if (!effect) {
+      throw new Error(`Unknown action effect with name: ${configId}`);
+    }
+    effect();
+  });
+
   function on(event: string, listener: Function) {
     listeners[event] = listeners[event] || [];
     listeners[event].push(listener);
@@ -135,6 +144,15 @@ export function initialize<T = {}>(): PluginInstance<T> {
       ) {
         void execPromise('wb:plugin:selection:set', id, elementId, selection);
       },
+      triggerAction(configId: string) {
+        void execPromise('wb:plugin:action-trigger:invoke', configId);
+      },
+      registerEffect(configId: string, effect: () => void) {
+        registeredEffects[configId] = effect;
+        return () => {
+          delete registeredEffects[configId];
+        };
+      },
       configureEditorPanel(options) {
         void execPromise('wb:plugin:config:inspector', options);
       },

src/react/hooks.ts

@@ -210,3 +210,36 @@ export function useInteraction(
 
   return [workbookInteraction, setInteraction];
 }
+
+/**
+ * React hook for returning a triggering callback function for the registered
+ * action trigger
+ * @param {string} configId ID of action trigger from the plugin config
+ * @returns {Function} A callback function to trigger the action
+ */
+export function useActionTrigger(configId: string): () => void {
+  const client = usePlugin();
+
+  return useCallback(() => {
+    client.config.triggerAction(configId);
+  }, [client, configId]);
+}
+
+/**
+ * React hook for registering and unregistering an action effect
+ * @param {string} configId ID of action effect from plugin config
+ * @param {Function} effect The function to be called when the action is triggered
+ */
+export function useActionEffect(configId: string, effect: () => void) {
+  const client = usePlugin();
+
+  const effectRef = useRef(effect);
+
+  useEffect(() => {
+    effectRef.current = effect;
+  });
+
+  useEffect(() => {
+    return client.config.registerEffect(configId, effectRef.current);
+  }, [client, configId, effect]);
+}

src/types.ts

@@ -166,6 +166,16 @@ export type CustomPluginConfigOptions =
       type: 'interaction';
       name: string;
       label?: string;
+    }
+  | {
+      type: 'action-trigger';
+      name: string;
+      label?: string;
+    }
+  | {
+      type: 'action-effect';
+      name: string;
+      label?: string;
     };
 
 /**
@@ -255,6 +265,20 @@ export interface PluginInstance<T = any> {
       selection: WorkbookSelection[],
     ): void;
 
+    /**
+     * Triggers an action based on the provided action trigger ID
+     * @param {string} configId ID from action-trigger type in Plugin Config
+     */
+    triggerAction(configId: string): void;
+
+    /**
+     * Registers an effect with the provided action effect ID
+     * @param {string} configId ID from action-effect type in Plugin Config
+     * @param effect The effect function to register
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    registerEffect(configId: string, effect: () => void): () => void;
+
     /**
      * Overrider function for Config Ready state
      * @param {boolean} loadingState Boolean representing if Plugin Config is still loading