@wordpress/ui 0.12.0 → 0.13.1-next.v.202605131006.0

package/src/dialog/stories/index.story.tsx

@@ -10,6 +10,7 @@ const meta: Meta< typeof Dialog.Root > = {
 	component: Dialog.Root,
 	subcomponents: {
 		'Dialog.Trigger': Dialog.Trigger,
+		'Dialog.Portal': Dialog.Portal,
 		'Dialog.Popup': Dialog.Popup,
 		'Dialog.Header': Dialog.Header,
 		'Dialog.Title': Dialog.Title,
@@ -25,6 +26,13 @@ const meta: Meta< typeof Dialog.Root > = {
 			options: [ true, false, 'trap-focus' ],
 		},
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/dialog/style.module.css

@@ -17,7 +17,7 @@
 		}
 
 		@media not (prefers-reduced-motion) {
-			transition: opacity 0.2s ease-out;
+			transition: opacity var(--wpds-motion-duration-md) var(--wpds-motion-easing-subtle);
 		}
 	}
 
@@ -60,14 +60,8 @@
 
 		@media not (prefers-reduced-motion) {
 			transition:
-				opacity 0.2s cubic-bezier(1, 0, 0.2, 1),
-				transform 0.2s cubic-bezier(1, 0, 0.2, 1);
-
-			&[data-open] {
-				transition:
-					opacity 0.2s cubic-bezier(0.29, 0, 0, 1),
-					transform 0.2s cubic-bezier(0.29, 0, 0, 1);
-			}
+				opacity var(--wpds-motion-duration-md) var(--wpds-motion-easing-expressive),
+				transform var(--wpds-motion-duration-md) var(--wpds-motion-easing-expressive);
 		}
 
 		@media (min-width: 480px) {

package/src/drawer/content.tsx

@@ -1,3 +1,4 @@
+import { mergeProps, useRender } from '@base-ui/react';
 import { Drawer as _Drawer } from '@base-ui/react/drawer';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
@@ -13,37 +14,51 @@ import type { ContentProps } from './types';
  *
  * **Required for scrolling** — `Drawer.Content` is the element that owns
  * the popup's overflow. Without it, body content that exceeds the popup's
- * available space clips instead of scrolling, and Base UI's
- * swipe-dismiss-on-scroll-edge logic will not engage on up/down drawers.
+ * available space clips instead of scrolling, and swipe-to-dismiss on
+ * scrollable vertical drawers won't gate correctly at the scroll edge.
  * Render it once per popup and wrap any freeform body content in it.
  *
  * Placing `Drawer.Header` or `Drawer.Footer` *inside* `Drawer.Content`
  * makes them scroll with the body (the "non-sticky" opt-out) rather than
  * staying pinned to the popup's edges.
  *
- * Renders Base UI's `_Drawer.Content` so swipe-dismiss wiring remains
- * wired automatically.
+ * Mouse-drag swipe-to-dismiss is preserved in the popup-edge padding
+ * gutter and on the chrome regions; mouse drag over the body itself
+ * does not dismiss the drawer, so text selection inside the body keeps
+ * working normally. Touch swipe-to-dismiss engages from anywhere in
+ * the popup (gated by the scroll edge on vertical drawers).
  */
 const Content = forwardRef< HTMLDivElement, ContentProps >(
-	function DrawerContent( { className, children, onScroll, ...props }, ref ) {
+	function DrawerContent(
+		{ className, render, children, onScroll, ...props },
+		ref
+	) {
 		const { ref: scrollStateRef, onScroll: scrollStateOnScroll } =
 			useOverlayScrollStateAttributes< HTMLDivElement >( onScroll );
 		const mergedRef = useMergeRefs( [ ref, scrollStateRef ] );
 
-		return (
-			<_Drawer.Content
-				ref={ mergedRef }
-				className={ clsx(
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref: mergedRef,
+			props: mergeProps< 'div' >( props, {
+				className: clsx(
 					styles.content,
 					focusStyles[ 'outset-ring--focus-visible' ],
 					className
-				) }
-				onScroll={ scrollStateOnScroll }
-				{ ...props }
-			>
-				{ children }
-			</_Drawer.Content>
-		);
+				),
+				onScroll: scrollStateOnScroll,
+				// `_Drawer.Content` carries the `[data-drawer-content]`
+				// marker that Base UI's swipe-dismiss logic uses to skip
+				// mouse-drag swipes started inside the body, preserving
+				// text selection. It must sit *inside* the scroll
+				// container so the popup's edge padding gutter falls
+				// outside the marker and stays mouse-draggable.
+				children: <_Drawer.Content>{ children }</_Drawer.Content>,
+			} ),
+		} );
+
+		return element;
 	}
 );
 

package/src/drawer/popup.tsx

@@ -9,7 +9,7 @@ import {
 import { unlock } from '../lock-unlock';
 import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
 import { SCROLL_CONTAINER_ATTR } from '../utils/use-overlay-scroll-state-attributes';
-import { renderPortalWithChildren } from '../utils/render-portal-with-children';
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import { DrawerValidationProvider, useDrawerModal } from './context';
 import { Portal } from './portal';
 import styles from './style.module.css';
@@ -24,8 +24,7 @@ const CLOSE_ICON_ATTR = 'data-wp-ui-drawer-close-icon';
  * Renders the drawer popup element that contains the drawer content.
  * Uses a portal to render outside the DOM hierarchy.
  *
- * When `portal` is omitted, defaults to `Drawer.Portal`. Portal merging is
- * handled by `renderPortalWithChildren` (shared with other overlay `Popup`s).
+ * When `portal` is omitted, defaults to `Drawer.Portal`.
  *
  * The popup is a flex column; scroll ownership lives on `Drawer.Content`,
  * which children are expected to render. Without it, long body content will
@@ -94,7 +93,7 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function DrawerPopup(
 		</>
 	);
 
-	return renderPortalWithChildren( portal, <Portal />, portalChildren );
+	return renderSlotWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };

package/src/drawer/stories/index.story.tsx

@@ -25,6 +25,13 @@ const meta: Meta< typeof Drawer.Root > = {
 			options: [ true, false, 'trap-focus' ],
 		},
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/drawer/style.module.css

@@ -91,20 +91,52 @@
 		color: var(--wpds-color-fg-content-neutral);
 		touch-action: auto;
 
+		/*
+		 * Hint compositing while the popup is in motion (opening, swiping,
+		 * or closing). Scoping `will-change` to these states avoids
+		 * retaining a transform layer while the drawer is fully idle.
+		 *
+		 * Limited to `transform` because that's the only animated property
+		 * the compositor can take off the main thread; `box-shadow` (also
+		 * transitioned below) is repainted on the main thread regardless,
+		 * so listing it here would just bloat the layer.
+		 */
 		&[data-open],
-		&[data-swiping] {
+		&[data-swiping],
+		&[data-ending-style] {
 			will-change: transform;
+		}
 
-			@media not (prefers-reduced-motion) {
-				transition: transform 450ms cubic-bezier(0.32, 0.72, 0, 1);
+		/*
+		 * Drop the elevation shadow while the popup is offscreen
+		 * (`[data-starting-style]` and `[data-ending-style]` translate the
+		 * popup fully past the viewport edge). The shadow's blur radius
+		 * would otherwise bleed back into the viewport at the screen edge,
+		 * appearing as a faint halo at mount/unmount instead of fading
+		 * with the slide. `box-shadow: none` interpolates against the
+		 * resolved token value as a list of zero-shadow layers.
+		 *
+		 * Kept outside the `prefers-reduced-motion` guard below so the
+		 * popup still mounts / unmounts without a stray shadow when
+		 * transitions are disabled — the value flips instantly to `none`
+		 * at the offscreen states, matching the instantaneous transform.
+		 */
+		&[data-starting-style],
+		&[data-ending-style] {
+			box-shadow: none;
+		}
+
+		@media not (prefers-reduced-motion) {
+			transition:
+				transform 450ms cubic-bezier(0.32, 0.72, 0, 1),
+				box-shadow 450ms cubic-bezier(0.32, 0.72, 0, 1);
 
-				&[data-ending-style] {
-					transition-duration: calc(var(--drawer-swipe-strength) * 400ms);
-				}
+			&[data-ending-style] {
+				transition-duration: calc(var(--drawer-swipe-strength) * 400ms);
+			}
 
-				&[data-swiping] {
-					transition-duration: 0ms;
-				}
+			&[data-swiping] {
+				transition-duration: 0ms;
 			}
 		}
 

package/src/drawer/test/index.test.tsx

@@ -810,6 +810,62 @@ describe( 'Drawer', () => {
 			);
 		} );
 
+		// Locks the wrapper structure that Drawer.Content relies on:
+		//
+		// - The forwarded ref / scroll listener / overlay-chrome class
+		//   must land on the visible scroll container (the outer div),
+		//   so it does NOT carry [data-drawer-content].
+		// - Base UI's [data-drawer-content] marker must sit *inside*
+		//   that scroll container so the popup-edge padding gutter
+		//   falls outside the marker and stays mouse-draggable for
+		//   swipe-dismiss (Base UI excludes mouse-drag swipe over
+		//   [data-drawer-content] to preserve text selection).
+		//
+		// Not asserted here: the marker rendering as a real block-level
+		// element rather than `display: contents` (which would neuter
+		// `useOverlayScrollStateAttributes`'s `ResizeObserver`). CSS
+		// modules resolve to empty stubs in this jsdom test environment,
+		// so a `display: contents` regression introduced via CSS would
+		// not be observable from `getComputedStyle`. Catching it
+		// requires reviewing the marker's stylesheet rules at code
+		// review time.
+		it( 'wraps a [data-drawer-content] marker as the only direct child', async () => {
+			const user = userEvent.setup();
+			const contentRef = createRef< HTMLDivElement >();
+
+			render(
+				<Drawer.Root>
+					<Drawer.Trigger>Open</Drawer.Trigger>
+					<Drawer.Popup>
+						<Drawer.Title>Title</Drawer.Title>
+						<Drawer.Content ref={ contentRef }>
+							<p>Body</p>
+						</Drawer.Content>
+					</Drawer.Popup>
+				</Drawer.Root>
+			);
+
+			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
+			await waitFor( () => {
+				expect( contentRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			expect( contentRef.current ).not.toHaveAttribute(
+				'data-drawer-content'
+			);
+
+			// Direct DOM access is intentional: this test locks the
+			// concrete element-level wrapping that other invariants
+			// (mouse-drag swipe-dismiss, ResizeObserver-driven scroll
+			// state) silently depend on.
+			// eslint-disable-next-line testing-library/no-node-access
+			const marker = contentRef.current?.firstElementChild;
+			expect( marker ).toBeInstanceOf( HTMLDivElement );
+			expect( marker ).toHaveAttribute( 'data-drawer-content' );
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( contentRef.current?.children ).toHaveLength( 1 );
+		} );
+
 		it( 'sets data-wp-ui-overlay-modal on the popup when modal is true', async () => {
 			const user = userEvent.setup();
 			const popupRef = createRef< HTMLDivElement >();

package/src/drawer/types.ts

@@ -101,7 +101,7 @@ export interface HeaderProps extends ComponentProps< 'header' > {
 
 export interface ContentProps extends ComponentProps< 'div' > {
 	/**
-	 * The body content to be rendered inside the scroll container.
+	 * The body content to be rendered inside the scroll region.
 	 */
 	children?: ReactNode;
 	/**

package/src/empty-state/stories/index.story.tsx

@@ -4,6 +4,7 @@ import { Button } from '../../button';
 import * as EmptyState from '../';
 
 const meta: Meta< typeof EmptyState.Root > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/EmptyState',
 	component: EmptyState.Root,
 	subcomponents: {
@@ -13,6 +14,12 @@ const meta: Meta< typeof EmptyState.Root > = {
 		'EmptyState.Description': EmptyState.Description,
 		'EmptyState.Actions': EmptyState.Actions,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/form/index.ts

@@ -1,3 +1,4 @@
 export * from './primitives';
 
 export * from './input-control';
+export * from './select-control';

package/src/form/input-control/stories/index.story.tsx

@@ -23,6 +23,13 @@ const meta: Meta< typeof InputControl > = {
 		value: { control: false },
 		type: { control: 'text' },
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

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

@@ -6,7 +6,7 @@ import {
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 import { unlock } from '../../../lock-unlock';
-import { renderPortalWithChildren } from '../../../utils/render-portal-with-children';
+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';
@@ -37,6 +37,6 @@ export const Popup = forwardRef< HTMLDivElement, AutocompletePopupProps >(
 			</_Autocomplete.Positioner>
 		);
 
-		return renderPortalWithChildren( portal, <Portal />, portalChildren );
+		return renderSlotWithChildren( portal, <Portal />, portalChildren );
 	}
 );

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

@@ -12,16 +12,24 @@ const meta: Meta< typeof Autocomplete.Root > = {
 	title: 'Design System/Components/Form/Primitives/Autocomplete',
 	component: Autocomplete.Root,
 	subcomponents: {
-		Popup: Autocomplete.Popup,
-		Input: Autocomplete.Input,
-		InputGroup: Autocomplete.InputGroup,
-		List: Autocomplete.List,
-		ListBody: Autocomplete.ListBody,
-		Collection: Autocomplete.Collection,
-		Item: Autocomplete.Item,
-		Value: Autocomplete.Value,
-		Empty: Autocomplete.Empty,
-		Clear: Autocomplete.Clear,
+		'Autocomplete.Portal': Autocomplete.Portal,
+		'Autocomplete.Popup': Autocomplete.Popup,
+		'Autocomplete.Input': Autocomplete.Input,
+		'Autocomplete.InputGroup': Autocomplete.InputGroup,
+		'Autocomplete.List': Autocomplete.List,
+		'Autocomplete.ListBody': Autocomplete.ListBody,
+		'Autocomplete.Collection': Autocomplete.Collection,
+		'Autocomplete.Item': Autocomplete.Item,
+		'Autocomplete.Value': Autocomplete.Value,
+		'Autocomplete.Empty': Autocomplete.Empty,
+		'Autocomplete.Clear': Autocomplete.Clear,
+	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`, overlays compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 };
 export default meta;

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

@@ -7,11 +7,18 @@ const meta: Meta< typeof Field.Root > = {
 	title: 'Design System/Components/Form/Primitives/Field',
 	component: Field.Root,
 	subcomponents: {
-		Item: Field.Item,
-		Label: Field.Label,
-		Control: Field.Control,
-		Description: Field.Description,
-		Details: Field.Details,
+		'Field.Item': Field.Item,
+		'Field.Label': Field.Label,
+		'Field.Control': Field.Control,
+		'Field.Description': Field.Description,
+		'Field.Details': Field.Details,
+	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components` and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 };
 export default meta;

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

@@ -6,9 +6,16 @@ const meta: Meta< typeof Fieldset.Root > = {
 	title: 'Design System/Components/Form/Primitives/Fieldset',
 	component: Fieldset.Root,
 	subcomponents: {
-		Legend: Fieldset.Legend,
-		Description: Fieldset.Description,
-		Details: Fieldset.Details,
+		'Fieldset.Legend': Fieldset.Legend,
+		'Fieldset.Description': Fieldset.Description,
+		'Fieldset.Details': Fieldset.Details,
+	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components` and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 };
 export default meta;

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

@@ -12,6 +12,13 @@ const meta: Meta< typeof Input > = {
 		value: { control: false },
 		type: { control: 'text' },
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/form/primitives/input-layout/stories/index.story.tsx

@@ -7,7 +7,14 @@ const meta: Meta< typeof InputLayout > = {
 	title: 'Design System/Components/Form/Primitives/InputLayout',
 	component: InputLayout,
 	subcomponents: {
-		Slot: InputLayout.Slot,
+		'InputLayout.Slot': InputLayout.Slot,
+	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 };
 export default meta;

package/src/form/primitives/select/item.tsx

@@ -9,7 +9,7 @@ import type { SelectItemProps } from './types';
 
 export const Item = forwardRef< HTMLDivElement, SelectItemProps >(
 	function Item(
-		{ className, value, size = 'default', children = value, ...restProps },
+		{ className, value, size = 'default', children, ...restProps },
 		ref
 	) {
 		return (

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

@@ -7,7 +7,7 @@ import {
 } from '@wordpress/theme';
 import { unlock } from '../../../lock-unlock';
 import { Portal } from './portal';
-import { renderPortalWithChildren } from '../../../utils/render-portal-with-children';
+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';
@@ -50,6 +50,6 @@ export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
 			</_Select.Positioner>
 		);
 
-		return renderPortalWithChildren( portal, <Portal />, portalChildren );
+		return renderSlotWithChildren( portal, <Portal />, portalChildren );
 	}
 );

package/src/form/primitives/select/root.tsx

@@ -1,6 +1,17 @@
 import { Select as _Select } from '@base-ui/react/select';
 import type { SelectRootProps } from './types';
 
-export function Root( props: SelectRootProps ) {
-	return <_Select.Root< string, false > { ...props } />;
+/**
+ * A component that lets users choose one option from a list.
+ *
+ * When using object values, pass an `items` array so `Select.Trigger` can
+ * auto-resolve the selected item's label. By default, items should use a
+ * `{ value, label }` shape, or provide `itemToStringLabel` for a custom shape.
+ *
+ * Object values are compared with `Object.is` by default, so use the same
+ * object references for `value` / `defaultValue` and `Select.Item` values, or
+ * provide `isItemEqualToValue`.
+ */
+export function Root< Value = unknown >( props: SelectRootProps< Value > ) {
+	return <_Select.Root< Value, false > { ...props } />;
 }