@bluealba/pae-ui-react-core 4.6.0-integration-css.403 → 4.6.0-integration-css.409

package/dist/src/styles/moduleStyleLifecycle.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Suspend/restore a micro-frontend module's global styles across single-spa
+ * mount/unmount.
+ *
+ * style-loader injects a module's CSS into document.head when the bundle is
+ * LOADED, and single-spa unmount never removes it (SystemJS keeps the module
+ * cached). A module that imports a global stylesheet (a CSS framework reset,
+ * preflight, etc.) therefore permanently contaminates every app visited
+ * afterwards in the same session.
+ *
+ * The UI SDK tags every <style> it emits with data-pae-module="<name>"
+ * (see pae-ui-react-sdk getBaseConfig). initializeMicroFrontend calls
+ * suspendModuleStyles on unmount — detaching those elements from the
+ * document while keeping them in memory — and restoreModuleStyles on mount,
+ * so re-entering the app is instant (no re-parse, CSSOM preserved).
+ *
+ * For modules that opt into per-module shadow DOM, restoreModuleStyles
+ * accepts the module's shadow root as target: the tagged styles are moved
+ * INTO the shadow root (scoping them to the module) instead of back into
+ * document.head, and suspendModuleStyles also sweeps that root on unmount.
+ *
+ * NOTE: this only covers CSS that goes through style-loader. Runtime
+ * CSS-in-JS (e.g. Emotion/MUI) injects its own tags and is not affected.
+ *
+ * pae-ui-react-core is a shared singleton (one instance via the import map),
+ * so this module-scoped store is global across all micro-frontends.
+ */
+/**
+ * Detach the module's style elements from the document (and from the given
+ * extra root, e.g. the module's shadow root), keeping them in memory for a
+ * later restoreModuleStyles call. Safe to call when the module has no tagged
+ * styles (no-op).
+ */
+export declare const suspendModuleStyles: (moduleName: string, extraRoot?: ParentNode) => void;
+/**
+ * Attach the module's style elements to the target (document.head by
+ * default, or the module's shadow root in per-module shadow DOM mode).
+ * Sources, in order: previously suspended elements, plus any still sitting
+ * in document.head when a non-document target is given (first mount of a
+ * shadow module — style-loader injected them at bundle load time).
+ * Safe to call when there is nothing to attach (no-op).
+ */
+export declare const restoreModuleStyles: (moduleName: string, target?: ShadowRoot) => void;

package/dist/src/utils/initializeMicroFrontend.d.ts

@@ -4,6 +4,32 @@ import { RootComponentProps } from '../MicrofrontendProps';
 
 export interface MicroFrontendOptions<T extends RootComponentProps> extends SingleSpaReactOpts<T> {
     rootComponent: FC<T>;
+    /**
+     * Mount this module inside its own shadow root (attached to the host
+     * element the platform resolves from ui.mountAtSelector).
+     *
+     * Why: global CSS from OTHER modules mounted at the same time (a framework
+     * reset, unlayered utilities, ...) cannot reach this module's DOM, and this
+     * module's own style-loader CSS is moved into the shadow root so it cannot
+     * leak out. This is the only isolation that works for SIMULTANEOUSLY
+     * mounted modules (e.g. fragments side by side) — the suspend/restore
+     * lifecycle alone only helps across navigation.
+     *
+     * What module authors must know:
+     * - Design tokens (CSS custom properties) inherit into the shadow root —
+     *   they keep working.
+     * - Selectors like `:root`, `html` or `body` do NOT match inside a shadow
+     *   root; use `:host` (Tailwind v4 already emits `:root, :host`).
+     * - @keyframes and @layer order statements are scoped per tree — keep them
+     *   in the module's own CSS (style-loader output is moved wholesale, so
+     *   this is automatic for bundled CSS).
+     * - Platform core components (Dialog, Tooltip) portal into the shadow root
+     *   automatically. Third-party overlay libraries default to document.body:
+     *   pass them the container from usePortalContainer(), and point runtime
+     *   CSS-in-JS (e.g. Emotion: createCache({ container })) at the shadow
+     *   root, or their floating content will render unstyled outside it.
+     */
+    shadowDom?: boolean;
 }
 /**
  * Main function to create a PAE micro-frontend module.
@@ -12,6 +38,13 @@ export interface MicroFrontendOptions<T extends RootComponentProps> extends Sing
  *
  * All PAE micro-frontends are wrapped in PAE components that provides react context later used
  * by the provided hooks.
+ *
+ * On top of the single-spa lifecycles, the module's global styles (tagged
+ * with data-pae-module by the UI SDK) are suspended on unmount and restored
+ * on mount, so CSS frameworks imported by one module don't leak into other
+ * modules across navigation (see styles/moduleStyleLifecycle). With
+ * `shadowDom: true` the module is additionally mounted inside its own shadow
+ * root, isolating it from modules mounted at the same time.
  */
-declare const initializeMicroFrontend: <T extends RootComponentProps>({ rootComponent, ...opts }: MicroFrontendOptions<T>) => ReactAppOrParcel<T>;
+declare const initializeMicroFrontend: <T extends RootComponentProps>({ rootComponent, shadowDom, ...opts }: MicroFrontendOptions<T>) => ReactAppOrParcel<T>;
 export default initializeMicroFrontend;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluealba/pae-ui-react-core",
-  "version": "4.6.0-integration-css.403",
+  "version": "4.6.0-integration-css.409",
   "type": "module",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",