u

src/automats/helpAutomat.js

@@ -3,11 +3,13 @@ import { Automat } from 'react-automat';
 /**
  * @typedef {Object} HelpState
  * @property {boolean} enabled Whether interactive help badges are enabled systemwide.
+ * @property {string|null} activeHelpId ID of the currently open help popper (only one can be open at a time).
  */
 
 /** @type {HelpState} */
 const initialState = {
   enabled: false,
+  activeHelpId: null,
 };
 
 /**
@@ -24,14 +26,46 @@ const helpAutomat = new Automat(
      * Toggles the systemwide help mode on or off.
      */
     toggle() {
-      helpAutomat.setState((prev) => ({ enabled: !prev?.enabled }));
+      helpAutomat.setState((prev) => {
+        const nextEnabled = !prev?.enabled;
+        return {
+          enabled: nextEnabled,
+          activeHelpId: nextEnabled ? prev?.activeHelpId ?? null : null,
+        };
+      });
     },
     /**
      * Explicitly set whether help mode is enabled.
      * @param {boolean} enabled
      */
     setEnabled(enabled) {
-      helpAutomat.setState({ enabled: Boolean(enabled) });
+      const nextEnabled = Boolean(enabled);
+      helpAutomat.setState((prev) => ({
+        enabled: nextEnabled,
+        activeHelpId: nextEnabled ? prev?.activeHelpId ?? null : null,
+      }));
+    },
+    /**
+     * Open a specific help popper, automatically closing any other currently open popper.
+     * @param {string} id
+     */
+    openPopper(id) {
+      helpAutomat.setState({ activeHelpId: id });
+    },
+    /**
+     * Close the currently active help popper.
+     */
+    closePopper() {
+      helpAutomat.setState({ activeHelpId: null });
+    },
+    /**
+     * Toggle a specific help popper open/closed.
+     * @param {string} id
+     */
+    togglePopper(id) {
+      helpAutomat.setState((prev) => ({
+        activeHelpId: prev?.activeHelpId === id ? null : id,
+      }));
     },
   },
   {
@@ -40,6 +74,20 @@ const helpAutomat = new Automat(
   }
 );
 
+// Clear active popper on initial boot / persistence hydration
+void helpAutomat.ready.then(() => {
+  if (helpAutomat.state?.activeHelpId) {
+    helpAutomat.setState({ activeHelpId: null });
+  }
+});
+
 export default helpAutomat;
-export const { toggle: toggleHelp, setEnabled: setHelpEnabled } = helpAutomat.actions;
+export const {
+  toggle: toggleHelp,
+  setEnabled: setHelpEnabled,
+  openPopper: openHelpPopper,
+  closePopper: closeHelpPopper,
+  togglePopper: toggleHelpPopper,
+} = helpAutomat.actions;
 export const isHelpEnabled = (state = helpAutomat.state) => Boolean(state?.enabled);
+export const selectActiveHelpId = (state = helpAutomat.state) => state?.activeHelpId ?? null;