@rimori/client 2.3.0-next.7 → 2.3.0-next.8

package/README.md

@@ -155,7 +155,7 @@ Use `client.runtime.fetchBackend` for authenticated calls to Rimori-managed HTTP
 - `on(topic, handler)` / `once(topic, handler)` / `respond(topic, handler)` – subscribe and reply (each call returns an object with `off()` for cleanup).
 - `emitAccomplishment(payload)` / `onAccomplishment(topic, handler)` – report learning milestones.
 - `emitSidebarAction(pluginId, actionKey, text?)` – trigger sidebar plugins.
-- `onMainPanelAction(handler, actionsToListen?)` – react to dashboard actions.
+- `onMainPanelAction(handler, actionsToListen?)` – react to dashboard actions. Returns an `EventListener` with an `off()` method. **Important:** Call `listener.off()` when your component unmounts or when you no longer need to listen, especially to prevent the event from firing again when navigating away from or returning to the page.
 - `client.navigation.toDashboard()` – navigate the user back to Rimori.
 
 ### Community Content

package/dist/plugin/RimoriClient.d.ts

@@ -143,6 +143,29 @@ export declare class RimoriClient {
          * @param text Optional text to be used for the action like for example text that the translator would look up.
          */
         emitSidebarAction: (pluginId: string, actionKey: string, text?: string) => void;
+        /**
+         * Subscribe to main panel actions triggered by the user from the dashboard.
+         * @param callback Handler function that receives the action data when a matching action is triggered.
+         * @param actionsToListen Optional filter to listen only to specific action keys. If empty or not provided, all actions will trigger the callback.
+         * @returns An EventListener object with an `off()` method for cleanup.
+         *
+         * @example
+         * ```ts
+         * const listener = client.event.onMainPanelAction((data) => {
+         *   console.log('Action received:', data.action_key);
+         * }, ['startSession', 'pauseSession']);
+         *
+         * // Clean up when component unmounts to prevent events from firing
+         * // when navigating away or returning to the page
+         * useEffect(() => {
+         *   return () => listener.off();
+         * }, []);
+         * ```
+         *
+         * **Important:** Always call `listener.off()` when your component unmounts or when you no longer need to listen.
+         * This prevents the event handler from firing when navigating away from or returning to the page, which could
+         * cause unexpected behavior or duplicate event handling.
+         */
         onMainPanelAction: (callback: (data: MainPanelAction) => void, actionsToListen?: string | string[]) => EventListener;
         onSidePanelAction: (callback: (data: MainPanelAction) => void, actionsToListen?: string | string[]) => EventListener;
     };

package/dist/plugin/RimoriClient.js

@@ -96,6 +96,29 @@ export class RimoriClient {
             emitSidebarAction: (pluginId, actionKey, text) => {
                 this.event.emit('global.sidebar.triggerAction', { plugin_id: pluginId, action_key: actionKey, text });
             },
+            /**
+             * Subscribe to main panel actions triggered by the user from the dashboard.
+             * @param callback Handler function that receives the action data when a matching action is triggered.
+             * @param actionsToListen Optional filter to listen only to specific action keys. If empty or not provided, all actions will trigger the callback.
+             * @returns An EventListener object with an `off()` method for cleanup.
+             *
+             * @example
+             * ```ts
+             * const listener = client.event.onMainPanelAction((data) => {
+             *   console.log('Action received:', data.action_key);
+             * }, ['startSession', 'pauseSession']);
+             *
+             * // Clean up when component unmounts to prevent events from firing
+             * // when navigating away or returning to the page
+             * useEffect(() => {
+             *   return () => listener.off();
+             * }, []);
+             * ```
+             *
+             * **Important:** Always call `listener.off()` when your component unmounts or when you no longer need to listen.
+             * This prevents the event handler from firing when navigating away from or returning to the page, which could
+             * cause unexpected behavior or duplicate event handling.
+             */
             onMainPanelAction: (callback, actionsToListen = []) => {
                 const listeningActions = Array.isArray(actionsToListen) ? actionsToListen : [actionsToListen];
                 // this needs to be a emit and on because the main panel action is triggered by the user and not by the plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimori/client",
-  "version": "2.3.0-next.7",
+  "version": "2.3.0-next.8",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {

package/src/plugin/RimoriClient.ts

@@ -260,6 +260,29 @@ export class RimoriClient {
       this.event.emit('global.sidebar.triggerAction', { plugin_id: pluginId, action_key: actionKey, text });
     },
 
+    /**
+     * Subscribe to main panel actions triggered by the user from the dashboard.
+     * @param callback Handler function that receives the action data when a matching action is triggered.
+     * @param actionsToListen Optional filter to listen only to specific action keys. If empty or not provided, all actions will trigger the callback.
+     * @returns An EventListener object with an `off()` method for cleanup.
+     *
+     * @example
+     * ```ts
+     * const listener = client.event.onMainPanelAction((data) => {
+     *   console.log('Action received:', data.action_key);
+     * }, ['startSession', 'pauseSession']);
+     *
+     * // Clean up when component unmounts to prevent events from firing
+     * // when navigating away or returning to the page
+     * useEffect(() => {
+     *   return () => listener.off();
+     * }, []);
+     * ```
+     *
+     * **Important:** Always call `listener.off()` when your component unmounts or when you no longer need to listen.
+     * This prevents the event handler from firing when navigating away from or returning to the page, which could
+     * cause unexpected behavior or duplicate event handling.
+     */
     onMainPanelAction: (
       callback: (data: MainPanelAction) => void,
       actionsToListen: string | string[] = [],