@wordpress/ui 0.13.1-next.v.202605131032.0 → 0.14.0

package/src/utils/css/wp-compat-overlay-slot.module.css

@@ -0,0 +1,35 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+/*
+ * Compat overlay slot — body-level positioned container that hosts
+ * `@wordpress/ui` overlays so they reliably stack in mixed-library
+ * compositions. See `getWpCompatOverlaySlot()` for the runtime side.
+ *
+ * The `.slot` rule is authored unlayered (outside `@layer wp-ui-*`) so the
+ * slot's z-index and positioning win against any `@layer`-scoped rule.
+ */
+
+.slot {
+	/* Viewport-sized so `position: absolute` overlay positioners inside
+	 * the slot have a non-zero containing block — otherwise `width: auto`
+	 * popups collapse to their min-content width. */
+	position: fixed;
+	inset: 0;
+	/* Reserved band above the legacy z-index map in
+	 * `packages/base-styles/_z-index.scss`. */
+	z-index: 1000000003;
+	isolation: isolate;
+	/* The slot itself doesn't capture clicks; portaled overlays opt back in
+	 * via the `.slot > *` rule below. */
+	pointer-events: none;
+}
+
+/*
+ * Re-enable interaction for portaled overlays. Placed in the lowest layer
+ * so any consumer can override with a higher-layer (or unlayered) rule.
+ */
+@layer wp-ui-utilities {
+	.slot > * {
+		pointer-events: auto;
+	}
+}

package/src/utils/render-slot-with-children.ts

@@ -27,5 +27,8 @@ export function renderSlotWithChildren(
 	defaultSlot: ReactElement,
 	children: ReactNode
 ): ReactElement {
-	return cloneElement( slot ?? defaultSlot, { children } );
+	return cloneElement(
+		( slot ?? defaultSlot ) as ReactElement< { children?: ReactNode } >,
+		{ children }
+	);
 }

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

@@ -0,0 +1,74 @@
+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;
+};
+
+// Slot is identified by a data attribute, not a user-facing role/text.
+/* 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() ).toBeUndefined();
+
+		render( <HookHost /> );
+
+		const slot = getWpCompatOverlaySlot();
+		expect( slot ).toBeDefined();
+		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() ).toBeDefined();
+		expect( findSlots() ).toHaveLength( 1 );
+	} );
+
+	it( 'leaves the slot enabled after the hook caller unmounts (one-way opt-in)', () => {
+		// Pins the one-way behavior — unmounting must not flip the gate
+		// back off; the slot is shared infrastructure.
+		const { unmount } = render( <HookHost /> );
+
+		expect( getWpCompatOverlaySlot() ).toBeDefined();
+
+		unmount();
+
+		expect( internalWindow.__wpUiCompatOverlaySlotEnabled ).toBe( true );
+		expect( getWpCompatOverlaySlot() ).toBeDefined();
+	} );
+} );
+
+/* eslint-enable testing-library/no-node-access */

package/src/utils/test/wp-compat-overlay-slot.test.ts

@@ -0,0 +1,300 @@
+import {
+	getWpCompatOverlaySlot,
+	WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE,
+	__resetWpCompatOverlaySlotCacheForTests,
+} from '../wp-compat-overlay-slot';
+
+// Typed accessors mirroring the helper's local casts: the flag and the
+// `wp` global are both intentionally undeclared on `Window` so the
+// package's published types don't leak augmentations.
+const internalWindow = window as unknown as {
+	__wpUiCompatOverlaySlotEnabled?: unknown;
+};
+const wpEnvWindow = window as unknown as {
+	wp?: { components?: unknown };
+};
+
+function findSlots(): HTMLElement[] {
+	return Array.from(
+		document.querySelectorAll< HTMLElement >(
+			`[${ WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE }]`
+		)
+	);
+}
+
+describe( 'getWpCompatOverlaySlot', () => {
+	afterEach( () => {
+		__resetWpCompatOverlaySlotCacheForTests();
+		findSlots().forEach( ( el ) => el.remove() );
+		delete internalWindow.__wpUiCompatOverlaySlotEnabled;
+		delete wpEnvWindow.wp;
+	} );
+
+	describe( 'explicit opt-in via internal flag', () => {
+		it( 'returns undefined when no gate is open', () => {
+			expect( getWpCompatOverlaySlot() ).toBeUndefined();
+			expect( findSlots() ).toHaveLength( 0 );
+		} );
+
+		it( 'returns undefined when the flag is explicitly false', () => {
+			internalWindow.__wpUiCompatOverlaySlotEnabled = false;
+
+			expect( getWpCompatOverlaySlot() ).toBeUndefined();
+			expect( findSlots() ).toHaveLength( 0 );
+		} );
+
+		it.each( [
+			[ '1', 1 ],
+			[ "'yes'", 'yes' ],
+			[ 'null', null ],
+			[ 'undefined', undefined ],
+		] )(
+			'returns undefined when the flag is %s (strict-equality gate)',
+			( _label, value ) => {
+				internalWindow.__wpUiCompatOverlaySlotEnabled = value;
+
+				expect( getWpCompatOverlaySlot() ).toBeUndefined();
+				expect( findSlots() ).toHaveLength( 0 );
+			}
+		);
+
+		it( 'creates and returns the slot when the flag is true', () => {
+			internalWindow.__wpUiCompatOverlaySlotEnabled = true;
+
+			const slot = getWpCompatOverlaySlot();
+
+			expect( slot ).toBeDefined();
+			expect( slot ).toBeInstanceOf( HTMLDivElement );
+			expect( slot?.parentElement ).toBe( document.body );
+			expect(
+				slot?.hasAttribute( WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE )
+			).toBe( true );
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+	} );
+
+	describe( 'WordPress environment auto-detection', () => {
+		it( 'auto-enables when window.wp.components is an object', () => {
+			wpEnvWindow.wp = { components: {} };
+
+			const slot = getWpCompatOverlaySlot();
+
+			expect( slot ).toBeDefined();
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+
+		it.each( [
+			[ 'a string', 'something' ],
+			[ 'a number', 42 ],
+			[ 'a boolean', true ],
+			[ 'undefined', undefined ],
+		] )(
+			'does not auto-enable when window.wp.components is %s',
+			( _label, value ) => {
+				wpEnvWindow.wp = { components: value };
+
+				expect( getWpCompatOverlaySlot() ).toBeUndefined();
+				expect( findSlots() ).toHaveLength( 0 );
+			}
+		);
+
+		it( 'does not auto-enable when window.wp.components is null', () => {
+			// `typeof null === 'object'` — pins the explicit null guard.
+			wpEnvWindow.wp = { components: null };
+
+			expect( getWpCompatOverlaySlot() ).toBeUndefined();
+			expect( findSlots() ).toHaveLength( 0 );
+		} );
+
+		it( 'does not auto-enable when window.wp itself is missing', () => {
+			expect( getWpCompatOverlaySlot() ).toBeUndefined();
+			expect( findSlots() ).toHaveLength( 0 );
+		} );
+
+		it( 'opens the gate even with the explicit flag absent', () => {
+			wpEnvWindow.wp = { components: {} };
+			expect(
+				internalWindow.__wpUiCompatOverlaySlotEnabled
+			).toBeUndefined();
+
+			expect( getWpCompatOverlaySlot() ).toBeDefined();
+		} );
+
+		// The cross-origin `window.top` throw path isn't unit-tested:
+		// jsdom's `window.top` is a non-configurable, non-writable getter,
+		// so the throw can't be simulated. Same-origin happy path is
+		// covered by every other auto-detect test; cross-origin is
+		// validated via manual smoke testing.
+	} );
+
+	describe( 'singleton caching', () => {
+		beforeEach( () => {
+			internalWindow.__wpUiCompatOverlaySlotEnabled = true;
+		} );
+
+		it( 'returns the same element on repeated calls', () => {
+			const first = getWpCompatOverlaySlot();
+			const second = getWpCompatOverlaySlot();
+			const third = getWpCompatOverlaySlot();
+
+			expect( first ).toBeDefined();
+			expect( second ).toBe( first );
+			expect( third ).toBe( first );
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+
+		it( 'creates a fresh element when the previous one was removed from the DOM, and re-caches it', () => {
+			const first = getWpCompatOverlaySlot();
+			expect( first ).toBeDefined();
+
+			first?.remove();
+			expect( findSlots() ).toHaveLength( 0 );
+
+			const second = getWpCompatOverlaySlot();
+
+			expect( second ).toBeDefined();
+			expect( second ).not.toBe( first );
+			expect( second?.isConnected ).toBe( true );
+			expect( findSlots() ).toHaveLength( 1 );
+
+			// A third call returns the cached recreated slot directly.
+			const third = getWpCompatOverlaySlot();
+			expect( third ).toBe( second );
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+
+		it( 'returns undefined after the gate is closed, even if a slot was previously created', () => {
+			const slot = getWpCompatOverlaySlot();
+			expect( slot ).toBeDefined();
+
+			delete internalWindow.__wpUiCompatOverlaySlotEnabled;
+
+			expect( getWpCompatOverlaySlot() ).toBeUndefined();
+		} );
+
+		it( 'invalidates the cache and detaches the stale slot when the cached element belongs to a different document', () => {
+			// Exercises the foreign-document cleanup branch by moving the
+			// cached slot into a parsed foreign document, so it stays
+			// `isConnected` but `ownerDocument` differs from the helper's
+			// local `document`.
+			const first = getWpCompatOverlaySlot();
+			expect( first ).toBeDefined();
+
+			const foreignDocument = new DOMParser().parseFromString(
+				'<!DOCTYPE html><html><body></body></html>',
+				'text/html'
+			);
+			foreignDocument.body.appendChild(
+				foreignDocument.adoptNode( first! )
+			);
+			expect( first?.ownerDocument ).toBe( foreignDocument );
+			expect( first?.isConnected ).toBe( true );
+			expect( findSlots() ).toHaveLength( 0 );
+
+			const second = getWpCompatOverlaySlot();
+
+			expect( second ).toBeDefined();
+			expect( second ).not.toBe( first );
+			expect( second?.ownerDocument ).toBe( document );
+			expect( second?.parentElement ).toBe( document.body );
+			expect( first?.isConnected ).toBe( false );
+			expect( foreignDocument.body.children ).toHaveLength( 0 );
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+	} );
+
+	describe( 'DOM-level singleton (cross-instance coordination)', () => {
+		beforeEach( () => {
+			internalWindow.__wpUiCompatOverlaySlotEnabled = true;
+		} );
+
+		it( 'adopts a pre-existing slot element rather than appending a duplicate', () => {
+			// Simulates a second `@wordpress/ui` instance creating the slot
+			// first: `cachedSlot` is null but the slot already exists in the DOM.
+			const preExisting = document.createElement( 'div' );
+			preExisting.setAttribute( WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE, '' );
+			document.body.appendChild( preExisting );
+
+			const slot = getWpCompatOverlaySlot();
+
+			expect( slot ).toBe( preExisting );
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+
+		it( 'caches the adopted slot for subsequent calls', () => {
+			const preExisting = document.createElement( 'div' );
+			preExisting.setAttribute( WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE, '' );
+			document.body.appendChild( preExisting );
+
+			const first = getWpCompatOverlaySlot();
+			const second = getWpCompatOverlaySlot();
+
+			expect( first ).toBe( preExisting );
+			expect( second ).toBe( preExisting );
+			expect( findSlots() ).toHaveLength( 1 );
+		} );
+	} );
+
+	describe( 'document.body unavailable', () => {
+		beforeEach( () => {
+			internalWindow.__wpUiCompatOverlaySlotEnabled = true;
+		} );
+
+		it( 'returns undefined without throwing when document.body is missing', () => {
+			const realBody = document.body;
+			const bodyDescriptor = Object.getOwnPropertyDescriptor(
+				Document.prototype,
+				'body'
+			);
+
+			Object.defineProperty( document, 'body', {
+				configurable: true,
+				get: () => null,
+			} );
+
+			try {
+				expect( () => getWpCompatOverlaySlot() ).not.toThrow();
+				expect( getWpCompatOverlaySlot() ).toBeUndefined();
+			} finally {
+				if ( bodyDescriptor ) {
+					Object.defineProperty( document, 'body', bodyDescriptor );
+				} else {
+					// Fallback if `body` wasn't on Document.prototype.
+					delete ( document as unknown as { body: unknown } ).body;
+				}
+				expect( document.body ).toBe( realBody );
+			}
+		} );
+	} );
+
+	describe( 'DOM identification', () => {
+		beforeEach( () => {
+			internalWindow.__wpUiCompatOverlaySlotEnabled = true;
+		} );
+
+		it( 'tags the element with the data-wp-compat-overlay-slot attribute (no value)', () => {
+			const slot = getWpCompatOverlaySlot();
+
+			expect(
+				slot?.getAttribute( WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE )
+			).toBe( '' );
+		} );
+
+		it( 'is discoverable via [data-wp-compat-overlay-slot] selector', () => {
+			const slot = getWpCompatOverlaySlot();
+
+			expect(
+				document.querySelector(
+					`[${ WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE }]`
+				)
+			).toBe( slot );
+		} );
+
+		it( 'appends the slot to the local document body', () => {
+			const slot = getWpCompatOverlaySlot();
+
+			expect( slot?.ownerDocument ).toBe( document );
+			expect( slot?.parentElement ).toBe( document.body );
+		} );
+	} );
+} );

package/src/utils/use-enable-wp-compat-overlay-slot.ts

@@ -0,0 +1,32 @@
+/**
+ * Opts the host application into the `@wordpress/ui` compat overlay slot —
+ * a body-level container into which `@wordpress/ui` overlays portal so they
+ * reliably stack above `@wordpress/components` overlays in mixed-library
+ * compositions.
+ *
+ * Call once from a component that mounts for the lifetime of the app
+ * (typically the root). Idempotent and one-way: a single caller should not
+ * be able to turn off shared infrastructure for everyone else; if the slot
+ * isn't wanted, simply don't call this hook.
+ *
+ * Where `window.wp.components` is on the global — the typical setup for
+ * plugins enqueueing `wp-components` through WordPress's script-loader —
+ * the slot auto-enables and this hook is a no-op.
+ */
+export function useEnableWpCompatOverlaySlot(): void {
+	if ( typeof window === 'undefined' ) {
+		return;
+	}
+
+	// Applied during render (not in `useLayoutEffect`) so descendants in
+	// the same render pass — e.g. `Tooltip.Portal`, which reads
+	// `getWpCompatOverlaySlot()` on every render — see the gate open on
+	// first mount. Safe to write during render: the value is an idempotent
+	// boolean.
+	const internalWindow = window as {
+		__wpUiCompatOverlaySlotEnabled?: boolean;
+	};
+	if ( internalWindow.__wpUiCompatOverlaySlotEnabled !== true ) {
+		internalWindow.__wpUiCompatOverlaySlotEnabled = true;
+	}
+}

package/src/utils/wp-compat-overlay-slot.ts

@@ -0,0 +1,129 @@
+import styles from './css/wp-compat-overlay-slot.module.css';
+
+// Local casts for the auto-detect heuristic and the shared opt-in flag,
+// kept off the global `Window` interface so this package's `.d.ts` doesn't
+// leak `Window.wp` / `Window.__wpUiCompatOverlaySlotEnabled` augmentations.
+type WpEnvironmentWindow = {
+	wp?: {
+		components?: unknown;
+	};
+};
+type CompatOverlaySlotInternalWindow = {
+	__wpUiCompatOverlaySlotEnabled?: boolean;
+};
+
+/**
+ * Marker attribute on the compat overlay slot element.
+ */
+export const WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE = 'data-wp-compat-overlay-slot';
+
+function resolveOwnerDocument(): Document | null {
+	// Always the local document — not `window.top?.document`, which would
+	// put the slot in a document where this bundle's CSS modules aren't
+	// loaded (e.g. Storybook's preview iframe).
+	return typeof document === 'undefined' ? null : document;
+}
+
+function isInWordPressEnvironment(): boolean {
+	let topWp: WpEnvironmentWindow[ 'wp' ];
+	try {
+		// Try the top window first so an iframe (e.g. the editor canvas)
+		// inherits the parent's WP environment.
+		topWp = ( window.top as WpEnvironmentWindow | undefined )?.wp;
+	} catch {
+		// Cross-origin top window — fall through to the local window.
+	}
+	const wp = topWp ?? ( window as WpEnvironmentWindow ).wp;
+	// Stricter than `!== undefined` so a stray non-object `components`
+	// doesn't trigger auto-enable. Explicit null check covers
+	// `typeof null === 'object'`.
+	return typeof wp?.components === 'object' && wp.components !== null;
+}
+
+// Revalidated on each call against the current owner document and the
+// slot's connection state.
+let cachedSlot: HTMLDivElement | null = null;
+
+function createSlot( ownerDocument: Document ): HTMLDivElement {
+	const element = ownerDocument.createElement( 'div' );
+	element.setAttribute( WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE, '' );
+	if ( styles.slot ) {
+		element.classList.add( styles.slot );
+	}
+	ownerDocument.body.appendChild( element );
+	return element;
+}
+
+/**
+ * Returns the body-level compat overlay slot when the runtime opts in,
+ * lazily creating it on first call. Returns `undefined` otherwise — so the
+ * return value can be forwarded straight to a `container` prop, leaving the
+ * default portal container in effect.
+ *
+ * Two opt-in paths:
+ *
+ * - Auto-detected when `window.wp.components` is on the global — the
+ *   typical script-loader setup for WordPress plugins and admin screens.
+ * - Explicit, via `useEnableWpCompatOverlaySlot()` — for hosts that bundle
+ *   `@wordpress/components` (or only `@wordpress/ui`) directly rather than
+ *   relying on the global.
+ *
+ * The slot is a single `<div data-wp-compat-overlay-slot>` appended to the
+ * local document's body. Subsequent calls return the same element; if it's
+ * been removed it's recreated, and a slot created by another
+ * `@wordpress/ui` instance in the same document is adopted rather than
+ * duplicated.
+ */
+export function getWpCompatOverlaySlot(): HTMLDivElement | undefined {
+	if ( typeof window === 'undefined' ) {
+		return undefined;
+	}
+
+	if (
+		! isInWordPressEnvironment() &&
+		( window as CompatOverlaySlotInternalWindow )
+			.__wpUiCompatOverlaySlotEnabled !== true
+	) {
+		return undefined;
+	}
+
+	const ownerDocument = resolveOwnerDocument();
+	// `document.body` can be null if this runs before `<body>` is parsed
+	// (e.g. a `<script>` in `<head>`). Bail rather than throw in `createSlot`.
+	if ( ! ownerDocument || ! ownerDocument.body ) {
+		return undefined;
+	}
+
+	if (
+		cachedSlot &&
+		cachedSlot.ownerDocument === ownerDocument &&
+		cachedSlot.isConnected
+	) {
+		return cachedSlot;
+	}
+
+	// Prefer an existing slot in the document over creating a duplicate —
+	// this is how multiple `@wordpress/ui` instances share one slot.
+	const existing = ownerDocument.querySelector< HTMLDivElement >(
+		`[${ WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE }]`
+	);
+	if ( existing instanceof HTMLDivElement ) {
+		cachedSlot = existing;
+		return existing;
+	}
+
+	// Don't orphan a cached slot still attached to a foreign document.
+	if ( cachedSlot?.isConnected ) {
+		cachedSlot.remove();
+	}
+
+	cachedSlot = createSlot( ownerDocument );
+	return cachedSlot;
+}
+
+/**
+ * Test-only escape hatch that drops the cached singleton.
+ */
+export function __resetWpCompatOverlaySlotCacheForTests(): void {
+	cachedSlot = null;
+}