@capillarytech/cap-ui-utils 3.0.15 → 3.0.17-alpha.0

package/index.js

@@ -12,3 +12,5 @@ export { default as sanitizeTemplateWithRegexp } from "./utils/contentSanitizati
 export { default as decompressJsonObject } from "./utils/zlibDataDecompress";
 export { default as getEnvVariable } from "./utils/getEnvVariables";
 export { formatDateWithTimezone, getTimezoneTooltip, hasTimezoneFeatureAccess } from "./utils/timezone";
+export { default as MFEEventBus } from "./utils/mfeEventBus";
+export { default as useMFEModuleHeader } from "./utils/useMFEModuleHeader";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capillarytech/cap-ui-utils",
-  "version": "3.0.15",
+  "version": "3.0.17-alpha.0",
   "description": "Utility functions shared accross all the modules",
   "main": "index.js",
   "scripts": {

package/utils/mfeEventBus.js

@@ -0,0 +1,47 @@
+/**
+ * MFEEventBus
+ *
+ * Lightweight event bus for cross-boundary communication between the MFE
+ * host shell and remote apps. Uses window CustomEvent — no build-time
+ * coupling between apps.
+ *
+ * All events are namespaced with the MFE_EVENT_PREFIX to avoid collisions
+ * with other window events (e.g. analytics, third-party libraries).
+ */
+
+const MFE_EVENT_PREFIX = 'mfe:';
+
+const MFEEventBus = {
+  /**
+   * Emit an event to all listeners (host or any remote).
+   *
+   * @param {string} eventName - Event name without prefix (e.g. 'loyalty:navigate')
+   * @param {object} payload   - Arbitrary serialisable data
+   */
+  emit(eventName, payload = {}) {
+    window.dispatchEvent(
+      new CustomEvent(`${MFE_EVENT_PREFIX}${eventName}`, {
+        detail: payload,
+        bubbles: false,
+        cancelable: false,
+      }),
+    );
+  },
+
+  /**
+   * Subscribe to an event. Returns an unsubscribe function — call it in
+   * useEffect cleanup to prevent memory leaks.
+   *
+   * @param {string}   eventName - Event name without prefix
+   * @param {function} handler   - Called with the event payload object
+   * @returns {function}         - Unsubscribe / cleanup function
+   */
+  on(eventName, handler) {
+    const listener = event => handler(event.detail);
+    window.addEventListener(`${MFE_EVENT_PREFIX}${eventName}`, listener);
+    return () =>
+      window.removeEventListener(`${MFE_EVENT_PREFIX}${eventName}`, listener);
+  },
+};
+
+export default MFEEventBus;

package/utils/useMFEModuleHeader.js

@@ -0,0 +1,133 @@
+import { useEffect, useRef } from 'react';
+import MFEEventBus from './mfeEventBus';
+
+/**
+ * Emit the module header for a given path. For route-based settings, the
+ * settings route shows the settings header (with a back button); everything
+ * else shows the main header. This runs on every navigation so both the MFE
+ * back button and the browser back button land on the correct header.
+ * No-op when settings is not route-based (header is registered once on mount).
+ */
+const emitHeaderForPath = (cfg, pathname) => {
+  const { header, settingsRoute, settingsHeader } = cfg;
+  if (!settingsRoute) return;
+  if (pathname.startsWith(settingsRoute)) {
+    MFEEventBus.emit('module:header-register', {
+      ...header,
+      ...settingsHeader,
+      showSettings: false,
+      showBackButton: true,
+    });
+  } else {
+    MFEEventBus.emit('module:header-register', header);
+  }
+};
+
+const emitRouteChange = pathname =>
+  MFEEventBus.emit('module:route-change', { pathname });
+
+/**
+ * useMFEModuleHeader
+ *
+ * Common hook wrapping the MFEEventBus module-header wiring duplicated across
+ * every remote app. Registers the module header, keeps it in sync on
+ * navigation (including browser back), and handles the settings button — for
+ * both modal-style settings (callback) and route-based settings (own URL).
+ *
+ * Router-version agnostic: it never calls useLocation/useNavigate itself
+ * (those throw without the matching Router context and break the rules of
+ * hooks when called conditionally). The caller passes the router primitives:
+ *   - React Router v5: pass `history` (history.location/.listen/.push/.goBack)
+ *   - React Router v6: pass `location` (from useLocation) and `navigate`
+ *     (from useNavigate)
+ * If both are passed, `history` (v5) takes precedence.
+ *
+ * Mount the hook in a component that stays rendered while the module is active
+ * AND is an ancestor of the header listener, so the listener subscribes before
+ * these emits fire — the bus has no replay for late subscribers.
+ *
+ * @param {object}    config
+ * @param {object}   [config.history]         React Router v5 history object
+ * @param {object}   [config.location]        React Router v6 location ({ pathname })
+ * @param {function} [config.navigate]        React Router v6 navigate function
+ * @param {object}    config.header           { name, description, showBorder, showSettings }
+ * @param {string[]} [config.landingRoutes]   Exact paths where the header is shown
+ * @param {function} [config.onSettingsClick] Modal settings handler (no route change)
+ * @param {string}   [config.settingsRoute]   Route-based settings URL (enables push/back)
+ * @param {object}   [config.settingsHeader]  { name, description } shown on settingsRoute
+ */
+export default function useMFEModuleHeader(config) {
+  const {
+    history,
+    location,
+    navigate,
+    header,
+    landingRoutes,
+    settingsRoute,
+  } = config;
+
+  const isRouteBased = Boolean(settingsRoute);
+  const showSettings = Boolean(header && header.showSettings);
+
+  // Latest config in a ref so callers can pass inline objects/handlers without
+  // memoizing: the long-lived listeners always read fresh values and never
+  // re-subscribe on identity changes (no stale closure, no churn).
+  const cfgRef = useRef(config);
+  cfgRef.current = config;
+
+  // Header register (non-route-based) + routes, once on mount.
+  useEffect(() => {
+    if (!isRouteBased) {
+      MFEEventBus.emit('module:header-register', header);
+    }
+    if (landingRoutes && landingRoutes.length) {
+      MFEEventBus.emit('module:header-routes', {
+        landingRoutes,
+        ...(isRouteBased ? { settingsRoute } : {}),
+      });
+    }
+    return () => MFEEventBus.emit('module:header-clear', {});
+  }, []);
+
+  // v5 navigation: single history.listen drives both header + route-change.
+  useEffect(() => {
+    if (!history) return undefined;
+    const { pathname } = history.location;
+    emitHeaderForPath(cfgRef.current, pathname);
+    emitRouteChange(pathname);
+    return history.listen(loc => {
+      emitHeaderForPath(cfgRef.current, loc.pathname);
+      emitRouteChange(loc.pathname);
+    });
+  }, [history]);
+
+  // v6 navigation: re-run on pathname change (skipped when v5 history is used).
+  useEffect(() => {
+    if (history || !location) return undefined;
+    emitHeaderForPath(cfgRef.current, location.pathname);
+    emitRouteChange(location.pathname);
+    return undefined;
+  }, [history, location && location.pathname]);
+
+  // Settings button.
+  useEffect(() => {
+    if (!showSettings) return undefined;
+    return MFEEventBus.on('module:settings-click', () => {
+      if (isRouteBased) {
+        if (history) history.push(settingsRoute);
+        else if (navigate) navigate(settingsRoute);
+      } else if (cfgRef.current.onSettingsClick) {
+        cfgRef.current.onSettingsClick();
+      }
+    });
+  }, [history, navigate, settingsRoute, showSettings]);
+
+  // Back button (route-based settings only).
+  useEffect(() => {
+    if (!isRouteBased) return undefined;
+    return MFEEventBus.on('module:back-click', () => {
+      if (history) history.goBack();
+      else if (navigate) navigate(-1);
+    });
+  }, [history, navigate, settingsRoute]);
+}