[ui] Add internal wp compat overlay slot helper

packages/ui/CHANGELOG.md

@@ -15,12 +15,20 @@
 -   `Drawer`: Restore the slide-out animation when the popup closes ([#77800](https://github.com/WordPress/gutenberg/pull/77800)).
 -   `Drawer`: Forward the `render` prop on `Drawer.Content` to the scroll container instead of leaking it as a DOM attribute, matching `Dialog.Content` ([#77941](https://github.com/WordPress/gutenberg/pull/77941)).
 
+### New Features
+
+-   Add `useEnableWpCompatOverlaySlot()` hook to opt into a body-level overlay container that stacks `@wordpress/ui` overlays above `@wordpress/components` overlays in mixed-library compositions. The slot auto-enables wherever `window.wp.components` is on the global (the typical script-loader setup for WordPress plugins and admin screens), so the hook is mostly relevant for hosts that bundle `@wordpress/components` (or only `@wordpress/ui`) directly — apps that aren't built with standard WordPress build tooling. Per-component support will be added incrementally ([#77851](https://github.com/WordPress/gutenberg/pull/77851)).
+
 ### Enhancements
 
 -   `Select`: Add a `placeholder` prop to `Select.Trigger`, and support `null` item values for clearable placeholder options ([#78076](https://github.com/WordPress/gutenberg/pull/78076)).
 -   `Drawer`: Fade the popup elevation shadow alongside the slide ([#77800](https://github.com/WordPress/gutenberg/pull/77800)).
 -   `Drawer`: Allow mouse-drag swipe-dismiss in the popup-edge padding gutter ([#77800](https://github.com/WordPress/gutenberg/pull/77800)).
 
+### Internal
+
+-   Add internal `getWpCompatOverlaySlot()` helper and a co-located unlayered CSS module that lazily provide a body-level `[data-wp-compat-overlay-slot]` container at z-index `1000000003`, gated by `useEnableWpCompatOverlaySlot()` and by auto-detection of `window.wp.components` ([#77851](https://github.com/WordPress/gutenberg/pull/77851)).
+
 ## 0.12.0 (2026-04-29)
 
 ### Breaking Changes

packages/ui/src/index.ts

@@ -17,4 +17,5 @@ export * from './stack';
 export * as Tabs from './tabs';
 export * from './text';
 export * as Tooltip from './tooltip';
+export { useEnableWpCompatOverlaySlot } from './utils/use-enable-wp-compat-overlay-slot';
 export * from './visually-hidden';

packages/ui/src/utils/css/wp-compat-overlay-slot.module.css

@@ -0,0 +1,46 @@
+/*
+ * WP compat overlay slot — body-level positioned container that hosts
+ * `@wordpress/ui` overlays so they reliably stack in mixed-library
+ * compositions. The `data-wp-compat-overlay-slot` attribute is the
+ * architectural identifier (see `getWpCompatOverlaySlot()`); `.slot` is
+ * the styling vehicle.
+ *
+ * Authored unlayered — outside `@layer wp-ui-*` — so the slot's z-index
+ * and positioning win against any `@layer`-scoped rule. CSS cascade
+ * layers always lose to unlayered styles, so unlayering is the ceiling.
+ *
+ * Why each declaration is what it is:
+ *
+ * - `z-index: 1000000003` — sits in a reserved billion-scale band above
+ *   the legacy z-index map in `packages/base-styles/_z-index.scss`.
+ *
+ * - `position: fixed` — load-bearing for two reasons. (1) `z-index` is
+ *   ignored on `position: static`. (2) A non-static position makes the
+ *   slot a containing block for absolute-positioned descendants;
+ *   floating-ui writes physical viewport-relative `top` / `left` onto
+ *   the floating element, so the containing block must sit at viewport
+ *   `(0, 0)`. `position: fixed` (with `top: 0; left: 0`) pins it there
+ *   regardless of scroll; `position: relative` would anchor at body's
+ *   flow position and silently break popover positioning.
+ *
+ * - `top: 0; left: 0` — physical, not logical. `inset-inline-start: 0`
+ *   would resolve to `right: 0` in RTL, anchoring the (zero-width) slot
+ *   at the viewport's top-right corner; an absolute child with
+ *   `left: 200px` would then resolve off the right edge of the screen.
+ *   Same hazard for `inset-block-start` under vertical writing modes.
+ *
+ * - `isolation: isolate` — redundant once `position: fixed` and
+ *   `z-index` are set (the slot is already a stacking context). Kept as
+ *   an explicit declaration of intent.
+ *
+ * The slot has zero content size, so it never intercepts pointer events.
+ */
+
+.slot {
+	position: fixed;
+	top: 0;
+	/* stylelint-disable-next-line plugin/use-logical-properties-and-values -- Physical anchoring required so floating-ui's viewport-relative coordinates resolve correctly; see file header. */
+	left: 0;
+	z-index: 1000000003;
+	isolation: isolate;
+}

packages/ui/src/utils/test/use-enable-wp-compat-overlay-slot.test.tsx

@@ -0,0 +1,79 @@
+import { render } from '@testing-library/react';
+import {
+	WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE,
+	getWpCompatOverlaySlot,
+	__resetWpCompatOverlaySlotCacheForTests,
+} from '../wp-compat-overlay-slot';
+import { useEnableWpCompatOverlaySlot } from '../use-enable-wp-compat-overlay-slot';
+
+const internalWindow = window as unknown as {
+	__wpUiCompatOverlaySlotEnabled?: boolean;
+};
+
+// The slot is identified by a data attribute (cross-tooling marker, not a
+// user-facing role/text), so direct DOM queries are appropriate here —
+// Testing Library's role/text accessors don't apply.
+/* eslint-disable testing-library/no-node-access */
+
+function findSlots(): HTMLElement[] {
+	return Array.from(
+		document.querySelectorAll< HTMLElement >(
+			`[${ WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE }]`
+		)
+	);
+}
+
+function HookHost() {
+	useEnableWpCompatOverlaySlot();
+	return null;
+}
+
+describe( 'useEnableWpCompatOverlaySlot', () => {
+	afterEach( () => {
+		__resetWpCompatOverlaySlotCacheForTests();
+		findSlots().forEach( ( el ) => el.remove() );
+		delete internalWindow.__wpUiCompatOverlaySlotEnabled;
+	} );
+
+	it( 'enables the slot once mounted, so getWpCompatOverlaySlot() returns the slot', () => {
+		expect( getWpCompatOverlaySlot() ).toBeNull();
+
+		render( <HookHost /> );
+
+		const slot = getWpCompatOverlaySlot();
+		expect( slot ).not.toBeNull();
+		expect( slot?.parentElement ).toBe( document.body );
+		expect( findSlots() ).toHaveLength( 1 );
+	} );
+
+	it( 'is idempotent across multiple components calling the hook', () => {
+		render(
+			<>
+				<HookHost />
+				<HookHost />
+				<HookHost />
+			</>
+		);
+
+		expect( getWpCompatOverlaySlot() ).not.toBeNull();
+		expect( findSlots() ).toHaveLength( 1 );
+	} );
+
+	it( 'leaves the slot enabled after the hook caller unmounts (one-way opt-in)', () => {
+		// The slot is shared infrastructure across all `@wordpress/ui`
+		// consumers in the document; a single component shouldn't be
+		// able to disable it for everyone else once enabled. This test
+		// pins that one-way behavior — unmounting the hook caller does
+		// not flip the gate back off.
+		const { unmount } = render( <HookHost /> );
+
+		expect( getWpCompatOverlaySlot() ).not.toBeNull();
+
+		unmount();
+
+		expect( internalWindow.__wpUiCompatOverlaySlotEnabled ).toBe( true );
+		expect( getWpCompatOverlaySlot() ).not.toBeNull();
+	} );
+} );
+
+/* eslint-enable testing-library/no-node-access */