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

package/package.json

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

package/utils/useMFEModuleHeader.js

@@ -2,28 +2,36 @@ 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).
+ * Register the module header for a given path. Resolution order:
+ *   1. settingsRoute prefix  -> settings header (back button, no settings icon)
+ *   2. first matching pathConfigs entry -> its header
+ *   3. fallback `header`
+ * Only used when the header is path-aware (settingsRoute or pathConfigs set);
+ * a purely static header is registered once on mount instead.
  */
-const emitHeaderForPath = (cfg, pathname) => {
-  const { header, settingsRoute, settingsHeader } = cfg;
-  if (!settingsRoute) return;
-  if (pathname.startsWith(settingsRoute)) {
+const registerHeaderForPath = (cfg, pathname) => {
+  const { pathConfigs, header, settingsRoute, settingsHeader } = cfg;
+  if (settingsRoute && pathname.startsWith(settingsRoute)) {
     MFEEventBus.emit('module:header-register', {
       ...header,
       ...settingsHeader,
       showSettings: false,
       showBackButton: true,
     });
-  } else {
-    MFEEventBus.emit('module:header-register', header);
+    return;
   }
+  if (pathConfigs && pathConfigs.length) {
+    const hit = pathConfigs.find(({ match }) =>
+      typeof match === 'function' ? match(pathname) : pathname.startsWith(match));
+    if (hit) {
+      MFEEventBus.emit('module:header-register', hit.header);
+      return;
+    }
+  }
+  if (header) MFEEventBus.emit('module:header-register', header);
 };
 
-const emitRouteChange = pathname =>
+const emitRouteChangeFor = pathname =>
   MFEEventBus.emit('module:route-change', { pathname });
 
 /**
@@ -31,12 +39,13 @@ const emitRouteChange = pathname =>
  *
  * 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).
+ * navigation (including browser back), and handles the settings/back buttons.
+ * Scales from a single static header (launchpad-style) up to a per-path header
+ * map with a header dropdown, extra buttons and arbitrary custom events (neo).
  *
- * 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:
+ * 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)
@@ -50,11 +59,20 @@ const emitRouteChange = pathname =>
  * @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 {object}   [config.header]          Default header, e.g.
+ *                                            { name, description, showBorder, showSettings, ...extra }
+ *                                            Any extra fields (showSelect, selectOptions,
+ *                                            extraButton, settingsRoute, ...) pass straight
+ *                                            through to the host.
+ * @param {Array}    [config.pathConfigs]     Path-aware header map, first match wins:
+ *                                            [{ match: string|((pathname)=>boolean), header }]
  * @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 {function} [config.onSettingsClick] Settings handler (modal / custom nav)
+ * @param {string}   [config.settingsRoute]   Route-based settings URL (enables push + back)
  * @param {object}   [config.settingsHeader]  { name, description } shown on settingsRoute
+ * @param {object}   [config.listeners]       { eventName: (payload)=>void } custom bus listeners
+ * @param {boolean}  [config.emitRouteChange] Emit module:route-change on nav (default true).
+ *                                            Set false to preserve repos that never emitted it.
  */
 export default function useMFEModuleHeader(config) {
   const {
@@ -64,10 +82,15 @@ export default function useMFEModuleHeader(config) {
     header,
     landingRoutes,
     settingsRoute,
+    pathConfigs,
+    onSettingsClick,
+    listeners,
+    emitRouteChange = true,
   } = config;
 
-  const isRouteBased = Boolean(settingsRoute);
-  const showSettings = Boolean(header && header.showSettings);
+  const isPathAware = Boolean(settingsRoute) || Boolean(pathConfigs && pathConfigs.length);
+  const hasSettingsClick = Boolean(settingsRoute) || Boolean(onSettingsClick);
+  const listenerNames = listeners ? Object.keys(listeners).sort().join(',') : '';
 
   // Latest config in a ref so callers can pass inline objects/handlers without
   // memoizing: the long-lived listeners always read fresh values and never
@@ -75,59 +98,73 @@ export default function useMFEModuleHeader(config) {
   const cfgRef = useRef(config);
   cfgRef.current = config;
 
-  // Header register (non-route-based) + routes, once on mount.
+  // Static header register (path-unaware) + routes, once on mount.
   useEffect(() => {
-    if (!isRouteBased) {
+    if (!isPathAware && header) {
       MFEEventBus.emit('module:header-register', header);
     }
     if (landingRoutes && landingRoutes.length) {
       MFEEventBus.emit('module:header-routes', {
         landingRoutes,
-        ...(isRouteBased ? { settingsRoute } : {}),
+        ...(settingsRoute ? { settingsRoute } : {}),
       });
     }
     return () => MFEEventBus.emit('module:header-clear', {});
   }, []);
 
-  // v5 navigation: single history.listen drives both header + route-change.
+  // v5 navigation: single history.listen drives path-aware header + route-change.
   useEffect(() => {
     if (!history) return undefined;
     const { pathname } = history.location;
-    emitHeaderForPath(cfgRef.current, pathname);
-    emitRouteChange(pathname);
+    if (isPathAware) registerHeaderForPath(cfgRef.current, pathname);
+    if (emitRouteChange) emitRouteChangeFor(pathname);
     return history.listen(loc => {
-      emitHeaderForPath(cfgRef.current, loc.pathname);
-      emitRouteChange(loc.pathname);
+      if (isPathAware) registerHeaderForPath(cfgRef.current, loc.pathname);
+      if (emitRouteChange) emitRouteChangeFor(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);
+    if (isPathAware) registerHeaderForPath(cfgRef.current, location.pathname);
+    if (emitRouteChange) emitRouteChangeFor(location.pathname);
     return undefined;
   }, [history, location && location.pathname]);
 
   // Settings button.
   useEffect(() => {
-    if (!showSettings) return undefined;
+    if (!hasSettingsClick) return undefined;
     return MFEEventBus.on('module:settings-click', () => {
-      if (isRouteBased) {
+      if (settingsRoute) {
         if (history) history.push(settingsRoute);
         else if (navigate) navigate(settingsRoute);
       } else if (cfgRef.current.onSettingsClick) {
         cfgRef.current.onSettingsClick();
       }
     });
-  }, [history, navigate, settingsRoute, showSettings]);
+  }, [history, navigate, settingsRoute, hasSettingsClick]);
 
-  // Back button (route-based settings only).
+  // Back button (route-based settings or path-aware headers with a back button).
   useEffect(() => {
-    if (!isRouteBased) return undefined;
+    if (!isPathAware) return undefined;
     return MFEEventBus.on('module:back-click', () => {
       if (history) history.goBack();
       else if (navigate) navigate(-1);
     });
-  }, [history, navigate, settingsRoute]);
+  }, [history, navigate, isPathAware]);
+
+  // Arbitrary custom event listeners. Handlers read from the ref so they can be
+  // inline; re-subscribes only when the set of event names changes.
+  useEffect(() => {
+    const map = cfgRef.current.listeners;
+    if (!map) return undefined;
+    const unsubs = Object.keys(map).map(name =>
+      MFEEventBus.on(name, payload => {
+        const fn = cfgRef.current.listeners && cfgRef.current.listeners[name];
+        if (fn) fn(payload);
+      }));
+    return () => unsubs.forEach(unsub => unsub());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [listenerNames]);
 }