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

package/src/collapsible-card/header.tsx

@@ -25,6 +25,8 @@ import type { HeaderProps } from './types';
  * Avoid placing interactive elements (buttons, links, inputs) inside the
  * header, since the entire area is clickable and their events will bubble
  * to trigger the collapse toggle.
+ *
+ * Place full-bleed media in `CollapsibleCard.Content`, not the header.
  */
 export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 	function CollapsibleCardHeader(

package/src/collapsible-card/stories/index.story.tsx

@@ -33,6 +33,7 @@ const meta: Meta< typeof CollapsibleCard.Root > = {
 		'CollapsibleCard.Header': CollapsibleCard.Header,
 		'CollapsibleCard.HeaderDescription': CollapsibleCard.HeaderDescription,
 		'CollapsibleCard.Content': CollapsibleCard.Content,
+		'Card.FullBleed': Card.FullBleed,
 	},
 	parameters: {
 		componentStatus: {
@@ -314,3 +315,68 @@ export const ComparedToCard: Story = {
 		</div>
 	),
 };
+
+/**
+ * When `Card.FullBleed` is the sole child of `CollapsibleCard.Content` and a
+ * header sits above it, the media bumps against the card&apos;s side and
+ * bottom edges while the header retains its normal padding. (Unlike a plain
+ * `Card`, a header is always required here for the collapse trigger — see
+ * `Card` stories for a body-only `FullBleedCoverOnly` example.)
+ */
+export const FullBleedCoverWithHeader: Story = {
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>Card title</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 180,
+								background:
+									'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * `Card.FullBleed` breaks out of the content padding to span edge-to-edge.
+ * Useful for images, dividers, or embedded content inside the collapsible
+ * region.
+ */
+export const WithFullBleed: Story = {
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>Featured image</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content
+					render={ <Stack direction="column" gap="lg" /> }
+				>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 160,
+								background:
+									'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+					<Text>Content below the full-bleed area.</Text>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};

package/src/dialog/portal.tsx

@@ -3,11 +3,7 @@ import { forwardRef } from '@wordpress/element';
 import type { PortalProps } from './types';
 
 /**
- * Root element that portals `Dialog` overlay content (`Backdrop`, inner
- * `Popup`, etc.) outside the DOM hierarchy. Pass to `Dialog.Popup`'s
- * `portal` prop to customize `container`, `className`, `style`, and other
- * Base UI portal options. When `portal` is omitted, `Dialog.Popup` uses this
- * component with default props.
+ * Used to apply custom portal behavior to `Dialog`'s overlay content.
  */
 const Portal = forwardRef< HTMLDivElement, PortalProps >(
 	function DialogPortal( props, ref ) {

package/src/dialog/types.ts

@@ -1,11 +1,11 @@
 import type { Dialog as _Dialog } from '@base-ui/react/dialog';
-import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 
 import type { Button } from '../button';
 import type { IconButton } from '../icon-button';
 import type { ComponentProps } from '../utils/types';
 
-export type PortalProps = ComponentPropsWithoutRef< typeof _Dialog.Portal >;
+export type PortalProps = ComponentProps< typeof _Dialog.Portal >;
 
 export interface RootProps
 	extends Pick<

package/src/drawer/portal.tsx

@@ -3,11 +3,7 @@ import { forwardRef } from '@wordpress/element';
 import type { PortalProps } from './types';
 
 /**
- * Root element that portals `Drawer` overlay content (`Backdrop`, `Viewport`
- * with the inner `Popup`, etc.) outside the DOM hierarchy. Pass to
- * `Drawer.Popup`'s `portal` prop to customize `container`, `className`,
- * `style`, and other Base UI portal options. When `portal` is omitted,
- * `Drawer.Popup` uses this component with default props.
+ * Used to apply custom portal behavior to `Drawer`'s overlay content.
  */
 const Portal = forwardRef< HTMLDivElement, PortalProps >(
 	function DrawerPortal( props, ref ) {

package/src/drawer/types.ts

@@ -1,10 +1,10 @@
 import type { Drawer as _Drawer } from '@base-ui/react/drawer';
-import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import type { Button } from '../button';
 import type { IconButton } from '../icon-button';
 import type { ComponentProps } from '../utils/types';
 
-export type PortalProps = ComponentPropsWithoutRef< typeof _Drawer.Portal >;
+export type PortalProps = ComponentProps< typeof _Drawer.Portal >;
 
 export interface RootProps
 	extends Pick<

package/src/form/primitives/autocomplete/clear.tsx

@@ -5,12 +5,18 @@ import { __ } from '@wordpress/i18n';
 import { IconButton } from '../../../icon-button';
 import type { AutocompleteClearProps } from './types';
 
-const DEFAULT_RENDER = ( {
-	'aria-label': ariaLabel = __( 'Clear' ),
-	...props
-}: AutocompleteClearProps ) => (
+const DEFAULT_RENDER = (
+	{
+		'aria-label': ariaLabel = __( 'Clear' ),
+		...props
+	}: AutocompleteClearProps,
+	{ disabled }: _Autocomplete.Clear.State
+) => (
 	<IconButton
 		icon={ closeSmall }
+		focusableWhenDisabled={ false }
+		disabled={ disabled }
+		aria-hidden={ disabled || undefined }
 		size="small"
 		variant="minimal"
 		tone="neutral"

package/src/form/primitives/autocomplete/index.ts

@@ -6,7 +6,8 @@ export { Input } from './input';
 export { Item } from './item';
 export { List } from './list';
 export { ListBody } from './list-body';
-export { Portal } from './portal';
 export { Popup } from './popup';
+export { Portal } from './portal';
+export { Positioner } from './positioner';
 export { Root } from './root';
 export { Value } from './value';

package/src/form/primitives/autocomplete/popup.tsx

@@ -8,35 +8,31 @@ import {
 import { unlock } from '../../../lock-unlock';
 import { renderSlotWithChildren } from '../../../utils/render-slot-with-children';
 import itemPopupStyles from '../../../utils/css/item-popup.module.css';
-import resetStyles from '../../../utils/css/resets.module.css';
-import styles from './style.module.css';
 import { Portal } from './portal';
+import { Positioner } from './positioner';
 import type { AutocompletePopupProps } from './types';
-import { ITEM_POPUP_POSITIONER_PROPS } from '../constants';
 
 const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, AutocompletePopupProps >(
-	function Popup( { className, portal, ...restProps }, ref ) {
-		const portalChildren = (
-			<_Autocomplete.Positioner
-				{ ...ITEM_POPUP_POSITIONER_PROPS }
-				className={ clsx(
-					resetStyles[ 'box-sizing' ],
-					styles.positioner
-				) }
-			>
-				<ThemeProvider>
-					<_Autocomplete.Popup
-						ref={ ref }
-						className={ clsx( itemPopupStyles.popup, className ) }
-						{ ...restProps }
-					/>
-				</ThemeProvider>
-			</_Autocomplete.Positioner>
+	function Popup( { className, portal, positioner, ...restProps }, ref ) {
+		const popupContent = (
+			<ThemeProvider>
+				<_Autocomplete.Popup
+					ref={ ref }
+					className={ clsx( itemPopupStyles.popup, className ) }
+					{ ...restProps }
+				/>
+			</ThemeProvider>
 		);
 
-		return renderSlotWithChildren( portal, <Portal />, portalChildren );
+		const positionedPopup = renderSlotWithChildren(
+			positioner,
+			<Positioner />,
+			popupContent
+		);
+
+		return renderSlotWithChildren( portal, <Portal />, positionedPopup );
 	}
 );

package/src/form/primitives/autocomplete/portal.tsx

@@ -1,15 +1,21 @@
 import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
 import { forwardRef } from '@wordpress/element';
 import type { PortalProps } from './types';
+import { getWpCompatOverlaySlot } from '../../../utils/wp-compat-overlay-slot';
 
 /**
- * Root element that portals `Autocomplete` popup content. Pass to
- * `Autocomplete.Popup`'s `portal` prop. When `portal` is omitted,
- * `Autocomplete.Popup` uses this component with default props.
+ * Used to apply custom portal behavior to `Autocomplete`'s popup content.
+ * `container` defaults to the `@wordpress/ui` compat overlay slot.
  */
 const Portal = forwardRef< HTMLDivElement, PortalProps >(
-	function AutocompletePortal( props, ref ) {
-		return <_Autocomplete.Portal ref={ ref } { ...props } />;
+	function AutocompletePortal( { container, ...restProps }, ref ) {
+		return (
+			<_Autocomplete.Portal
+				container={ container ?? getWpCompatOverlaySlot() }
+				{ ...restProps }
+				ref={ ref }
+			/>
+		);
 	}
 );
 

package/src/form/primitives/autocomplete/positioner.tsx

@@ -0,0 +1,29 @@
+import clsx from 'clsx';
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import { forwardRef } from '@wordpress/element';
+import type { PositionerProps } from './types';
+import resetStyles from '../../../utils/css/resets.module.css';
+import styles from './style.module.css';
+import { ITEM_POPUP_POSITIONER_PROPS } from '../constants';
+
+/**
+ * Used to apply custom positioning to `Autocomplete`'s popup content.
+ */
+const Positioner = forwardRef< HTMLDivElement, PositionerProps >(
+	function AutocompletePositioner( { className, ...props }, ref ) {
+		return (
+			<_Autocomplete.Positioner
+				{ ...ITEM_POPUP_POSITIONER_PROPS }
+				{ ...props }
+				ref={ ref }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner,
+					className
+				) }
+			/>
+		);
+	}
+);
+
+export { Positioner };

package/src/form/primitives/autocomplete/stories/index.story.tsx

@@ -13,6 +13,7 @@ const meta: Meta< typeof Autocomplete.Root > = {
 	component: Autocomplete.Root,
 	subcomponents: {
 		'Autocomplete.Portal': Autocomplete.Portal,
+		'Autocomplete.Positioner': Autocomplete.Positioner,
 		'Autocomplete.Popup': Autocomplete.Popup,
 		'Autocomplete.Input': Autocomplete.Input,
 		'Autocomplete.InputGroup': Autocomplete.InputGroup,

package/src/form/primitives/autocomplete/test/index.test.tsx

@@ -1,7 +1,9 @@
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
+import type { ReactNode } from 'react';
 import * as Autocomplete from '../index';
+import { useEnableWpCompatOverlaySlot } from '../../../../utils/use-enable-wp-compat-overlay-slot';
 
 const ITEMS = [
 	{ id: '1', value: 'Item 1' },
@@ -9,6 +11,15 @@ const ITEMS = [
 	{ id: '3', value: 'Item 3' },
 ];
 
+function renderDisabledAutocompleteWithClear() {
+	return render(
+		<Autocomplete.Root items={ ITEMS } disabled defaultValue="Item 1">
+			<Autocomplete.Input placeholder="Search" />
+			<Autocomplete.Clear />
+		</Autocomplete.Root>
+	);
+}
+
 describe( 'Autocomplete', () => {
 	it( 'forwards ref', async () => {
 		const user = userEvent.setup();
@@ -159,4 +170,212 @@ describe( 'Autocomplete', () => {
 			);
 		} );
 	} );
+
+	describe( 'positioner', () => {
+		it( 'should render the custom positioner element wrapping the popup content', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Autocomplete.Root items={ ITEMS }>
+					<Autocomplete.Input placeholder="Search" />
+					<Autocomplete.Popup
+						positioner={
+							<Autocomplete.Positioner data-testid="custom-positioner" />
+						}
+					>
+						<Autocomplete.List>
+							<Autocomplete.ListBody>
+								<Autocomplete.Collection>
+									{ ( item ) => (
+										<Autocomplete.Item
+											key={ item.id }
+											value={ item }
+										>
+											{ item.value }
+										</Autocomplete.Item>
+									) }
+								</Autocomplete.Collection>
+							</Autocomplete.ListBody>
+						</Autocomplete.List>
+					</Autocomplete.Popup>
+				</Autocomplete.Root>
+			);
+
+			await user.type( screen.getByRole( 'combobox' ), 'Item 1' );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			const positioner = screen.getByTestId( 'custom-positioner' );
+
+			expect( positioner ).toContainElement( item );
+		} );
+	} );
+
+	// Slot is identified by a data attribute, not a user-facing role/text.
+	/* eslint-disable testing-library/no-node-access */
+	describe( 'wp compat overlay slot', () => {
+		const SLOT_SELECTOR = '[data-wp-compat-overlay-slot]';
+
+		// Exercises the public opt-in path rather than poking the flag.
+		function WithSlotEnabled( { children }: { children: ReactNode } ) {
+			useEnableWpCompatOverlaySlot();
+			return <>{ children }</>;
+		}
+
+		afterEach( () => {
+			// The hook is one-way at runtime; reset explicitly between tests.
+			delete ( window as { __wpUiCompatOverlaySlotEnabled?: boolean } )
+				.__wpUiCompatOverlaySlotEnabled;
+			document
+				.querySelectorAll( SLOT_SELECTOR )
+				.forEach( ( el ) => el.remove() );
+		} );
+
+		it( 'portals the popup into the slot when the consumer opts in', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<WithSlotEnabled>
+					<Autocomplete.Root items={ ITEMS }>
+						<Autocomplete.Input placeholder="Search" />
+						<Autocomplete.Popup>
+							<Autocomplete.List>
+								<Autocomplete.ListBody>
+									<Autocomplete.Collection>
+										{ ( item ) => (
+											<Autocomplete.Item
+												key={ item.id }
+												value={ item }
+											>
+												{ item.value }
+											</Autocomplete.Item>
+										) }
+									</Autocomplete.Collection>
+								</Autocomplete.ListBody>
+							</Autocomplete.List>
+						</Autocomplete.Popup>
+					</Autocomplete.Root>
+				</WithSlotEnabled>
+			);
+
+			await user.type( screen.getByRole( 'combobox' ), 'Item 1' );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			const slot = document.querySelector( SLOT_SELECTOR );
+			expect( slot ).not.toBeNull();
+			expect( slot ).toContainElement( item );
+		} );
+
+		it( 'does not create a slot when the consumer has not opted in (dormant default)', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Autocomplete.Root items={ ITEMS }>
+					<Autocomplete.Input placeholder="Search" />
+					<Autocomplete.Popup>
+						<Autocomplete.List>
+							<Autocomplete.ListBody>
+								<Autocomplete.Collection>
+									{ ( item ) => (
+										<Autocomplete.Item
+											key={ item.id }
+											value={ item }
+										>
+											{ item.value }
+										</Autocomplete.Item>
+									) }
+								</Autocomplete.Collection>
+							</Autocomplete.ListBody>
+						</Autocomplete.List>
+					</Autocomplete.Popup>
+				</Autocomplete.Root>
+			);
+
+			await user.type( screen.getByRole( 'combobox' ), 'Item 1' );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			expect( document.querySelector( SLOT_SELECTOR ) ).toBeNull();
+		} );
+
+		it( 'lets a caller-supplied portal container override the slot', async () => {
+			const user = userEvent.setup();
+			const containerRef = createRef< HTMLDivElement >();
+
+			render(
+				<WithSlotEnabled>
+					<Autocomplete.Root items={ ITEMS }>
+						<Autocomplete.Input placeholder="Search" />
+						<div
+							ref={ containerRef }
+							data-testid="custom-container"
+						/>
+						<Autocomplete.Popup
+							portal={
+								<Autocomplete.Portal
+									container={ containerRef }
+								/>
+							}
+						>
+							<Autocomplete.List>
+								<Autocomplete.ListBody>
+									<Autocomplete.Collection>
+										{ ( item ) => (
+											<Autocomplete.Item
+												key={ item.id }
+												value={ item }
+											>
+												{ item.value }
+											</Autocomplete.Item>
+										) }
+									</Autocomplete.Collection>
+								</Autocomplete.ListBody>
+							</Autocomplete.List>
+						</Autocomplete.Popup>
+					</Autocomplete.Root>
+				</WithSlotEnabled>
+			);
+
+			await user.type( screen.getByRole( 'combobox' ), 'Item 1' );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+			expect( screen.getByTestId( 'custom-container' ) ).toContainElement(
+				item
+			);
+		} );
+	} );
+	/* eslint-enable testing-library/no-node-access */
+
+	describe( 'when disabled', () => {
+		it( 'hides the clear button from screen readers', () => {
+			renderDisabledAutocompleteWithClear();
+
+			expect(
+				screen.queryByRole( 'button', { name: 'Clear' } )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'does not show a tooltip when the clear button is hovered', async () => {
+			const user = userEvent.setup( { pointerEventsCheck: 0 } );
+			renderDisabledAutocompleteWithClear();
+
+			const clearButton = screen.getByLabelText( 'Clear', {
+				selector: 'button',
+			} );
+			await user.hover( clearButton );
+
+			expect( screen.queryByRole( 'tooltip' ) ).not.toBeInTheDocument();
+		} );
+	} );
 } );

package/src/form/primitives/autocomplete/types.ts

@@ -1,12 +1,12 @@
 import type { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
-import type { ComponentPropsWithoutRef, ReactElement } from 'react';
+import type { ReactElement } from 'react';
 import type { ComponentProps } from '../../../utils/types';
 
 export type AutocompleteCollectionProps = _Autocomplete.Collection.Props;
 
-export type PortalProps = ComponentPropsWithoutRef<
-	typeof _Autocomplete.Portal
->;
+export type PortalProps = ComponentProps< typeof _Autocomplete.Portal >;
+
+export type PositionerProps = ComponentProps< typeof _Autocomplete.Positioner >;
 
 export type AutocompleteClearProps = ComponentProps<
 	typeof _Autocomplete.Clear
@@ -58,17 +58,17 @@ export type AutocompletePopupProps = ComponentProps<
 	 * portal element; they would be ignored.
 	 */
 	portal?: ReactElement< Omit< PortalProps, 'children' > >;
-};
-
-export type AutocompleteRootProps = ComponentProps<
-	typeof _Autocomplete.Root
-> & {
-	children?: React.ReactNode;
-};
-
-export type AutocompleteValueProps = {
 	/**
-	 * Can be used to override the current value of the autocomplete.
+	 * Optional positioner element, typically `<Autocomplete.Positioner />`
+	 * with custom positioning props (`side`, `align`, `sideOffset`, collision
+	 * settings, etc.). When omitted, `Autocomplete.Popup` uses
+	 * `Autocomplete.Positioner` with default props. Do not pass `children` on
+	 * the positioner element; they would be ignored.
 	 */
-	children?: _Autocomplete.Value.Props[ 'children' ];
+	positioner?: ReactElement< Omit< PositionerProps, 'children' > >;
 };
+
+export type AutocompleteRootProps< Value = unknown > =
+	_Autocomplete.Root.Props< Value >;
+
+export type AutocompleteValueProps = _Autocomplete.Value.Props;

package/src/form/primitives/constants.ts

@@ -1,10 +1,13 @@
-import type { Select as _Select } from '@base-ui/react/select';
-
 /**
- * Shared positioning props for item popups (Select, Combobox, etc.).
+ * Shared positioning defaults for item-list popups. Consumed as individual
+ * default values by `Select.Positioner` and `Autocomplete.Positioner`. Each
+ * key is validated by the consuming positioner's prop types at the use
+ * site, so a value here that does not satisfy either Base UI positioner's
+ * type will surface as a type error in `select/positioner.tsx` or
+ * `autocomplete/positioner.tsx`.
  */
 export const ITEM_POPUP_POSITIONER_PROPS = {
 	align: 'start',
 	sideOffset: 8,
 	collisionPadding: 12,
-} satisfies Partial< _Select.Positioner.Props >;
+} as const;

package/src/form/primitives/select/index.ts

@@ -1,5 +1,6 @@
 export { Item } from './item';
-export { Portal } from './portal';
 export { Popup } from './popup';
+export { Portal } from './portal';
+export { Positioner } from './positioner';
 export { Root } from './root';
 export { Trigger } from './trigger';