@bluealba/pae-ui-react-core 4.7.0 → 4.8.0

package/dist/src/components/PortalContainerContext.d.ts

@@ -0,0 +1,12 @@
+import { FC, ReactNode } from 'react';
+
+export interface PortalContainerProviderProps {
+    container: HTMLElement | null;
+    children: ReactNode;
+}
+export declare const PortalContainerProvider: FC<PortalContainerProviderProps>;
+/**
+ * Returns the portal container to use, or undefined to let Radix default to
+ * document.body.
+ */
+export declare const usePortalContainer: () => HTMLElement | undefined;

package/dist/src/components/ThemeToggle/useTheme.d.ts

@@ -1,4 +1,4 @@
 export declare const useTheme: () => {
-    theme: "light" | "dark";
+    theme: "dark" | "light";
     setTheme: (value: "light" | "dark") => void;
 };

package/dist/src/components/index.d.ts

@@ -8,3 +8,5 @@ export { default as ThemeToggle } from './ThemeToggle/ThemeToggle';
 export { useTheme } from './ThemeToggle/useTheme';
 export { default as FragmentSlot } from './FragmentSlot';
 export type { FragmentSlotProps } from './FragmentSlot';
+export { PortalContainerProvider, usePortalContainer } from './PortalContainerContext';
+export type { PortalContainerProviderProps } from './PortalContainerContext';

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

@@ -4,7 +4,45 @@ 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 a dedicated child
+     * of the host element the platform resolves from ui.mountAtSelector, so the
+     * shared host stays usable by other modules mounted there later).
+     *
+     * 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 DOM cannot be affected by it. This is the only isolation
+     * that works for SIMULTANEOUSLY mounted modules (e.g. fragments side by side).
+     *
+     * 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` instead.
+     * - CSS built with the SDK (`pae-ui-sdk`) is automatically encapsulated. The
+     *   module's `<style data-pae-module>` nodes are kept out of the light-DOM
+     *   `document.head` and live inside the shadow root, including lazy chunks and
+     *   HMR updates. No extra setup needed for webpack-imported stylesheets.
+     * - If you inject styles by other means (e.g. dynamic `<style>` creation,
+     *   third-party runtime CSS-in-JS), access the shadow root via:
+     *   `usePortalContainer()?.getRootNode() as ShadowRoot | undefined`
+     * - Platform core components (Dialog, Tooltip) portal into the shadow root
+     *   automatically when the module author passes the container from
+     *   `usePortalContainer()` to the `container` prop of their portal component.
+     *   Third-party overlay libraries default to document.body: pass them the
+     *   container from `usePortalContainer()` to keep them inside the shadow root.
+     */
+    shadowDom?: boolean;
 }
+/**
+ * Marker set on a shadow module's exported `mount` so other core code can detect,
+ * after a bare `System.import` (e.g. reading a module's `menu`/`icon` without
+ * mounting it), that the module is shadow-isolated and its styles must be evacuated
+ * from `document.head`. See {@link hasShadowDomMarker} and useApplicationJSModule.
+ */
+export declare const SHADOW_DOM_MARKER = "__paeShadowDom";
+/** True if `mount` is a shadow module's lifecycle (carries {@link SHADOW_DOM_MARKER}). */
+export declare const hasShadowDomMarker: (mount: unknown) => boolean;
 /**
  * Main function to create a PAE micro-frontend module.
  * Internally we use single-spa so currently our API is pretty similar.
@@ -12,6 +50,10 @@ 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.
+ *
+ * When `shadowDom: true` is passed the module is mounted inside its own open shadow
+ * root (see {@link withShadowDom}), isolating it from global CSS in the light DOM and
+ * keeping its own CSS out of `document.head`.
  */
-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/dist/src/utils/moduleStyleRegistry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-module style routing registry, shared process-wide via `window`.
+ *
+ * The CSS of an isolated (`shadowDom`) micro-frontend must never leak into the
+ * light-DOM `document.head`. style-loader injects `<style data-pae-module=name>`
+ * nodes into the head at bundle-load (e.g. when the shell imports a module just to
+ * read its `menu`/`icon`, long before — or without ever — mounting it). This
+ * registry holds, per module, a DETACHED holder element that owns those nodes
+ * while the module is not mounted (a detached node is not rendered, so its CSS does
+ * not apply ⇒ no leak), plus the current `target` where new nodes should go.
+ *
+ * `initializeMicroFrontend` flips `target` across the lifecycle (holder ⇄ shadow
+ * root) and `useApplicationJSModule` evacuates a shadow module's head styles into
+ * the holder right after importing it for its exports.
+ */
+export interface StyleEntry {
+    /** The module name (equals the `data-pae-module` attribute of its style nodes). */
+    name: string;
+    /** Where newly injected `<style data-pae-module=name>` nodes should be placed now. */
+    target: Node;
+    /** Detached `<div>` that owns the module's style nodes while it is not mounted. */
+    holder: HTMLElement;
+    mode: 'detached' | 'shadow';
+}
+/** Get or lazily create the registry entry (with a detached holder) for a module. */
+export declare const getStyleEntry: (moduleName: string) => StyleEntry;
+/**
+ * Move every `<style|link data-pae-module=name>` node currently under `from` into
+ * `to`. Used to evacuate a module's styles out of `document.head` (into its holder
+ * or shadow root) and back into the holder on unmount.
+ */
+export declare const moveModuleStyles: (from: ParentNode, to: Node, name: string) => void;
+/**
+ * Evacuate a shadow module's styles out of the light-DOM `document.head` into its
+ * detached holder, and route future styles there too — unless the module is
+ * currently mounted (its target is the live shadow root). Returns the entry.
+ */
+export declare const evacuateToHolder: (moduleName: string) => StyleEntry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluealba/pae-ui-react-core",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "type": "module",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",