@wordpress/ui 0.11.0 → 0.12.0

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

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Input, InputLayout } from '../../../..';
+import { Input } from '../';
+import { InputLayout } from '../../input-layout';
 import { WithSuffixControl } from '../../input-layout/stories/index.story';
 
 const meta: Meta< typeof Input > = {

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { copy } from '@wordpress/icons';
-import { IconButton, InputLayout } from '../../../..';
+import { InputLayout } from '../';
+import { IconButton } from '../../../../icon-button';
 
 const meta: Meta< typeof InputLayout > = {
 	title: 'Design System/Components/Form/Primitives/InputLayout',

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

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

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

@@ -27,7 +27,6 @@ export const Item = forwardRef< HTMLDivElement, SelectItemProps >(
 				<Icon
 					icon={ check }
 					className={ clsx(
-						itemPopupStyles[ 'item-indicator' ],
 						itemPopupStyles[ 'item-indicator-icon' ]
 					) }
 					size={ size === 'small' ? 20 : 24 }

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

@@ -6,6 +6,8 @@ import {
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 import { unlock } from '../../../lock-unlock';
+import { Portal } from './portal';
+import { renderPortalWithChildren } from '../../../utils/render-portal-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';
@@ -16,43 +18,38 @@ const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
-	function Popup(
-		{ className, container, children, style, ...restProps },
-		ref
-	) {
-		return (
-			<_Select.Portal container={ container }>
-				<_Select.Positioner
-					{ ...ITEM_POPUP_POSITIONER_PROPS }
-					alignItemWithTrigger={ false }
-					style={ style }
-					className={ clsx(
-						resetStyles[ 'box-sizing' ],
-						styles.positioner,
-						className
-					) }
-				>
-					<ThemeProvider>
-						<_Select.Popup
-							ref={ ref }
-							className={ itemPopupStyles.popup }
-							{ ...restProps }
-						>
-							<_Select.List className={ itemPopupStyles.list }>
-								<div
-									className={
-										itemPopupStyles[
-											'list-scrollable-container'
-										]
-									}
-								>
-									{ children }
-								</div>
-							</_Select.List>
-						</_Select.Popup>
-					</ThemeProvider>
-				</_Select.Positioner>
-			</_Select.Portal>
+	function Popup( { className, portal, children, ...restProps }, ref ) {
+		const portalChildren = (
+			<_Select.Positioner
+				{ ...ITEM_POPUP_POSITIONER_PROPS }
+				alignItemWithTrigger={ false }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner
+				) }
+			>
+				<ThemeProvider>
+					<_Select.Popup
+						ref={ ref }
+						className={ clsx( itemPopupStyles.popup, className ) }
+						{ ...restProps }
+					>
+						<_Select.List className={ itemPopupStyles.list }>
+							<div
+								className={
+									itemPopupStyles[
+										'list-scrollable-container'
+									]
+								}
+							>
+								{ children }
+							</div>
+						</_Select.List>
+					</_Select.Popup>
+				</ThemeProvider>
+			</_Select.Positioner>
 		);
+
+		return renderPortalWithChildren( portal, <Portal />, portalChildren );
 	}
 );

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

@@ -0,0 +1,16 @@
+import { Select as _Select } from '@base-ui/react/select';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * Root element that portals `Select` listbox content. Pass to
+ * `Select.Popup`'s `portal` prop. When `portal` is omitted, `Select.Popup`
+ * uses this component with default props.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function SelectPortal( props, ref ) {
+		return <_Select.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

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

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Select } from '../../../..';
+import * as Select from '../';
 
 const meta: Meta< typeof Select.Root > = {
 	title: 'Design System/Components/Form/Primitives/Select',
@@ -251,12 +251,20 @@ export const WithCustomTriggerAndItem: Story = {
 };
 
 /**
- * Popovers in Gutenberg are managed with explicit z-index values, which can create
- * situations where a popover renders below another popover, when you want it to be rendered above.
+ * Popovers in Gutenberg are managed with explicit z-index values, which can
+ * create situations where a select popup renders below another popover when
+ * you want it above.
  *
- * The `--wp-ui-select-z-index` CSS variable, available on the `Select.Popup` component,
- * is an escape hatch that can be used to override the z-index of a given `Select` popover
- * on a case-by-case basis.
+ * The `--wp-ui-select-z-index` CSS variable controls the z-index of the
+ * `Select` positioner. Override it either:
+ *
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   `Select` popover in the page), or
+ * - **Per instance**, by passing a `Select.Portal` with a `style` (or
+ *   `className`) to `Select.Popup`'s `portal` prop. The variable cascades
+ *   from the portal wrapper to everything rendered inside it.
+ *
+ * This story demonstrates the per-instance approach.
  */
 export const WithCustomZIndex: Story = {
 	name: 'With Custom z-index',
@@ -264,7 +272,13 @@ export const WithCustomZIndex: Story = {
 		children: (
 			<>
 				<Select.Trigger />
-				<Select.Popup style={ { '--wp-ui-select-z-index': '1000001' } }>
+				<Select.Popup
+					portal={
+						<Select.Portal
+							style={ { '--wp-ui-select-z-index': '9999' } }
+						/>
+					}
+				>
 					<Select.Item value="Item 1" />
 					<Select.Item value="Item 2" />
 				</Select.Popup>

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

@@ -31,8 +31,8 @@ describe( 'Select', () => {
 		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
 
-	describe( 'container', () => {
-		it( 'should render inside the container when provided', async () => {
+	describe( 'portal', () => {
+		it( 'should render inside the portal container when a custom target is provided', async () => {
 			const user = userEvent.setup();
 			const containerRef = createRef< HTMLDivElement >();
 
@@ -44,7 +44,11 @@ describe( 'Select', () => {
 							ref={ containerRef }
 							data-testid="custom-container"
 						/>
-						<Select.Popup container={ containerRef }>
+						<Select.Popup
+							portal={
+								<Select.Portal container={ containerRef } />
+							}
+						>
 							<Select.Item value="Item 1" />
 						</Select.Popup>
 					</Select.Root>

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

@@ -1,7 +1,11 @@
 import type { Select as _Select } from '@base-ui/react/select';
+import type { ComponentPropsWithoutRef, ReactElement } from 'react';
+
 import type { ComponentProps } from '../../../utils/types';
 import type { InputLayoutProps } from '../input-layout/types';
 
+export type PortalProps = ComponentPropsWithoutRef< typeof _Select.Portal >;
+
 // The second type parameter is the `multiple` flag (currently disabled).
 export type SelectRootProps = Omit<
 	_Select.Root.Props< string, false >,
@@ -34,9 +38,12 @@ export type SelectPopupProps = ComponentProps< typeof _Select.Popup > & {
 	 */
 	children?: React.ReactNode;
 	/**
-	 * A parent element to render the portal into.
+	 * Optional portal element, typically `<Select.Portal />` with custom
+	 * `container`. When omitted, `Select.Popup` uses `Select.Portal` with
+	 * default props. Do not pass `children` on the portal element; they would
+	 * be ignored.
 	 */
-	container?: _Select.Portal.Props[ 'container' ];
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
 };
 
 export type SelectItemProps = Omit<

package/src/index.ts

@@ -5,6 +5,7 @@ export * as Collapsible from './collapsible';
 export * as CollapsibleCard from './collapsible-card';
 export * as AlertDialog from './alert-dialog';
 export * as Dialog from './dialog';
+export * as Drawer from './drawer';
 export * as EmptyState from './empty-state';
 export * from './form';
 export * from './icon';

package/src/link/link.tsx

@@ -20,20 +20,10 @@ export const Link = forwardRef< HTMLAnchorElement, LinkProps >( function Link(
 		openInNewTab = false,
 		render,
 		className,
-		onClick,
 		...props
 	},
 	ref
 ) {
-	const isInternalAnchor = !! props.href?.startsWith( '#' );
-
-	const handleClick = ( event: React.MouseEvent< HTMLAnchorElement > ) => {
-		if ( openInNewTab && isInternalAnchor ) {
-			event.preventDefault();
-		}
-		onClick?.( event );
-	};
-
 	const element = useRender( {
 		render,
 		defaultTagName: 'a',
@@ -46,27 +36,23 @@ export const Link = forwardRef< HTMLAnchorElement, LinkProps >( function Link(
 				variant !== 'unstyled' && styles.link,
 				variant !== 'unstyled' && styles[ `is-${ tone }` ],
 				variant === 'unstyled' && styles[ 'is-unstyled' ],
-				openInNewTab && styles[ 'has-link-icon' ],
 				className
 			),
-			onClick: handleClick,
 			target: openInNewTab ? '_blank' : undefined,
-			children: openInNewTab ? (
+			children: (
 				<>
-					<span className={ styles[ 'link-contents' ] }>
-						{ children }
-					</span>
-					<span
-						className={ styles[ 'link-icon' ] }
-						role="img"
-						aria-label={
-							/* translators: accessibility text appended to link text */
-							__( '(opens in a new tab)' )
-						}
-					/>
+					{ children }
+					{ openInNewTab && (
+						<span
+							className={ styles[ 'link-icon' ] }
+							role="img"
+							aria-label={
+								/* translators: accessibility text appended to link text */
+								__( '(opens in a new tab)' )
+							}
+						/>
+					) }
 				</>
-			) : (
-				children
 			),
 		} ),
 	} );

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

@@ -6,6 +6,7 @@ import { Text } from '../../text';
 const meta: Meta< typeof Link > = {
 	title: 'Design System/Components/Link',
 	component: Link,
+	tags: [ 'manifest' ],
 };
 export default meta;
 
@@ -66,9 +67,8 @@ export const Inline: Story = {
 };
 
 /**
- * When composing `Text` and `Link` via the `render` prop, the order matters:
- * - `<Text render={ <Link /> } />` renders an `<a>` element (Link's default tag wins).
- * - `<Link render={ <Text /> } />` renders a `<span>` element (Text's default tag wins).
+ * When composing `Text` and `Link` via the `render` prop, keep `Text` as the
+ * host and pass `Link` via `render` so the resulting element stays an `<a>`.
  */
 export const Standalone: Story = {
 	args: {
@@ -80,13 +80,8 @@ export const Standalone: Story = {
 		},
 	},
 	render: ( args ) => (
-		<Stack direction="column" gap="md">
-			<Text variant="body-md" render={ <Link { ...args } /> }>
-				A standalone link with body-md typography
-			</Text>
-			<Text variant="body-sm" render={ <Link { ...args } /> }>
-				A standalone link with body-sm typography
-			</Text>
-		</Stack>
+		<Text variant="body-md" render={ <Link { ...args } /> }>
+			A standalone link with body-md typography
+		</Text>
 	),
 };

package/src/link/style.module.css

@@ -3,7 +3,7 @@
 @layer wp-ui-components {
 	.link {
 		text-underline-offset: 0.2em;
-		text-decoration-thickness: 0.5px;
+		text-decoration-thickness: from-font;
 	}
 
 	/* Brand tone */
@@ -46,26 +46,14 @@
 	}
 
 	/* Link icon pattern — arrow rendered via ::after pseudo-element to avoid
-	 * Twemoji replacement and text-selection issues. Root <a> gets
-	 * text-decoration:none; the link-contents span re-applies it.
-	 * text-underline-offset is inherited and propagates from .link
-	 * automatically. text-decoration-thickness and text-decoration-color
-	 * are NOT inherited, so they are explicitly redeclared on
-	 * .link-contents (the latter via `inherit` to carry the neutral
-	 * tone's custom color token through). */
-	.has-link-icon {
-		text-decoration: none;
-	}
-
-	.link-contents {
-		text-decoration: underline;
-		text-decoration-color: inherit;
-		text-decoration-thickness: 0.5px;
-	}
+	 * Twemoji replacement and text-selection issues. The icon is an
+	 * inline-block so the link underline stays scoped to the text. */
 
 	.link-icon {
+		display: inline-block;
 		margin-inline-start: var(--wpds-dimension-padding-xs);
 		font-weight: var(--wpds-typography-font-weight-regular);
+		text-decoration: none;
 	}
 
 	.link-icon::after {

package/src/link/test/index.test.tsx

@@ -16,6 +16,24 @@ describe( 'Link', () => {
 		expect( ref.current ).toBeInstanceOf( HTMLAnchorElement );
 	} );
 
+	it( 'calls onClick when clicked (often used for analytics tracking)', async () => {
+		const user = userEvent.setup();
+		const onClick = jest.fn(
+			( event: React.MouseEvent< HTMLAnchorElement > ) =>
+				event.preventDefault()
+		);
+
+		render(
+			<Link href="/page" onClick={ onClick }>
+				Go to page
+			</Link>
+		);
+
+		await user.click( screen.getByRole( 'link', { name: 'Go to page' } ) );
+
+		expect( onClick ).toHaveBeenCalledTimes( 1 );
+	} );
+
 	describe( 'openInNewTab', () => {
 		it( 'sets target="_blank" when true', () => {
 			render(
@@ -47,47 +65,33 @@ describe( 'Link', () => {
 
 			expect(
 				screen.getByLabelText( '(opens in a new tab)' )
-			).toBeInTheDocument();
+			).toBeVisible();
 		} );
 
-		it( 'prevents default for internal anchor links', async () => {
-			const user = userEvent.setup();
-			const onClick = jest.fn();
-
+		it( 'keeps the link text on the anchor element', () => {
 			render(
-				<Link href="#section" openInNewTab onClick={ onClick }>
-					Jump
+				<Link href="https://example.com" openInNewTab>
+					External
 				</Link>
 			);
 
-			await user.click( screen.getByRole( 'link' ) );
-
-			expect( onClick ).toHaveBeenCalledTimes( 1 );
-			expect( onClick.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe(
-				true
+			expect( screen.getByText( 'External' ) ).toBe(
+				screen.getByRole( 'link' )
 			);
 		} );
 
-		it( 'does not prevent default for external links', async () => {
-			const user = userEvent.setup();
-			const onClick = jest.fn();
-
+		it( 'includes the new tab notice in the link name', () => {
 			render(
-				<Link
-					href="https://example.com"
-					openInNewTab
-					onClick={ onClick }
-				>
+				<Link href="https://example.com" openInNewTab>
 					External
 				</Link>
 			);
 
-			await user.click( screen.getByRole( 'link' ) );
-
-			expect( onClick ).toHaveBeenCalledTimes( 1 );
-			expect( onClick.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe(
-				false
-			);
+			expect(
+				screen.getByRole( 'link', {
+					name: 'External (opens in a new tab)',
+				} )
+			).toBeVisible();
 		} );
 	} );
 } );

package/src/link/types.ts

@@ -22,8 +22,7 @@ export interface LinkProps extends Omit< ComponentProps< 'a' >, 'target' > {
 
 	/**
 	 * Whether to open the link in a new browser tab.
-	 * When true, sets `target="_blank"`, appends a visual arrow indicator,
-	 * and prevents navigation for internal anchors (`#`-prefixed hrefs).
+	 * When true, sets `target="_blank"` and appends a visual arrow indicator.
 	 *
 	 * @default false
 	 */

package/src/notice/action-link.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { Link } from '../link';
+import { Text } from '../text';
 import type { ActionLinkProps } from './types';
 import styles from './style.module.css';
 
@@ -8,14 +9,16 @@ import styles from './style.module.css';
  * An action link for use within Notice.Actions.
  */
 export const ActionLink = forwardRef< HTMLAnchorElement, ActionLinkProps >(
-	function NoticeActionLink( { className, ...props }, ref ) {
+	function NoticeActionLink( { className, render, ...props }, ref ) {
 		return (
-			<Link
+			<Text
 				ref={ ref }
 				className={ clsx( styles[ 'action-link' ], className ) }
 				{ ...props }
-				tone="neutral"
-				variant="default"
+				variant="body-md"
+				render={
+					<Link tone="neutral" variant="default" render={ render } />
+				}
 			/>
 		);
 	}

package/src/notice/style.module.css

@@ -64,11 +64,6 @@
 
 	.action-link {
 		flex-shrink: 0;
-		font-family: var(--wpds-typography-font-family-body);
-		font-size: var(--wpds-typography-font-size-md);
-		font-weight: var(--wpds-typography-font-weight-regular);
-		line-height: var(--wpds-typography-line-height-sm);
-		margin-block: auto;
 
 		/* Add more horizontal space when following another action link/button */
 		&:not(:first-child) {
@@ -125,6 +120,11 @@
 }
 
 @layer wp-ui-compositions {
+	/* Override `Text` margin */
+	.action-link {
+		margin-block: auto;
+	}
+
 	/* Add partial transparency to CloseIcon and outline/minimal ActionButton
 	 * for a better look over tinted backgrounds */
 	.close-icon,

package/src/popover/context.tsx

@@ -1,100 +1,17 @@
-import {
-	createContext,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-} from '@wordpress/element';
+import { createOverlayTitleValidation } from '../utils/create-overlay-title-validation';
 
-/**
- * Whether validation is enabled. This is a build-time constant that allows
- * bundlers to tree-shake all validation code in production builds.
- */
-const VALIDATION_ENABLED = process.env.NODE_ENV !== 'production';
-
-type PopoverValidationContextType = {
-	registerTitle: ( element: HTMLElement | null ) => void;
-};
-
-const PopoverValidationContext = VALIDATION_ENABLED
-	? createContext< PopoverValidationContextType | null >( null )
-	: ( null as unknown as React.Context< PopoverValidationContextType | null > );
-
-function usePopoverValidationContextDev() {
-	return useContext( PopoverValidationContext );
-}
-
-function usePopoverValidationContextProd() {
-	return null;
-}
+const popoverTitleValidation = createOverlayTitleValidation( 'Popover' );
 
 /**
  * Hook to access the popover validation context.
  * Returns null in production or if not within a Popover.Popup.
  */
-export const usePopoverValidationContext = VALIDATION_ENABLED
-	? usePopoverValidationContextDev
-	: usePopoverValidationContextProd;
-
-/**
- * Development-only provider that tracks whether Popover.Title is rendered.
- */
-function PopoverValidationProviderDev( {
-	children,
-}: {
-	children: React.ReactNode;
-} ) {
-	const titleElementRef = useRef< HTMLElement | null >( null );
-
-	const registerTitle = useCallback( ( element: HTMLElement | null ) => {
-		titleElementRef.current = element;
-	}, [] );
-
-	const contextValue = useMemo(
-		() => ( { registerTitle } ),
-		[ registerTitle ]
-	);
-
-	useEffect( () => {
-		const titleElement = titleElementRef.current;
-
-		if ( ! titleElement ) {
-			throw new Error(
-				'Popover: Missing <Popover.Title>. ' +
-					'For accessibility, every popover requires a title. ' +
-					'If needed, the title can be visually hidden but must not be omitted.'
-			);
-		}
-
-		const textContent = titleElement.textContent?.trim();
-		if ( ! textContent ) {
-			throw new Error(
-				'Popover: <Popover.Title> cannot be empty. ' +
-					'Provide meaningful text content for the popover title.'
-			);
-		}
-	}, [] );
-
-	return (
-		<PopoverValidationContext.Provider value={ contextValue }>
-			{ children }
-		</PopoverValidationContext.Provider>
-	);
-}
-
-function PopoverValidationProviderProd( {
-	children,
-}: {
-	children: React.ReactNode;
-} ) {
-	return <>{ children }</>;
-}
+export const usePopoverValidationContext =
+	popoverTitleValidation.useValidationContext;
 
 /**
  * Provider component that validates Popover.Title presence in development mode.
  * In production, this component is a no-op and just renders children.
  */
-export const PopoverValidationProvider = VALIDATION_ENABLED
-	? PopoverValidationProviderDev
-	: PopoverValidationProviderProd;
+export const PopoverValidationProvider =
+	popoverTitleValidation.ValidationProvider;

package/src/popover/description.tsx

@@ -1,24 +1,20 @@
 import { Popover as _Popover } from '@base-ui/react/popover';
-import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { Text } from '../text';
-import styles from './style.module.css';
 import type { DescriptionProps } from './types';
 
 /**
  * Renders an optional paragraph that describes the popover content.
  *
  * The rendered element is linked to the popup via `aria-describedby`.
- * Uses the `body-md` text variant by default.
  */
 const Description = forwardRef< HTMLParagraphElement, DescriptionProps >(
-	function PopoverDescription( { className, children, ...props }, ref ) {
+	function PopoverDescription( { children, ...props }, ref ) {
 		return (
 			<Text
 				ref={ ref }
 				variant="body-md"
 				render={ <_Popover.Description { ...props } /> }
-				className={ clsx( styles.description, className ) }
 			>
 				{ children }
 			</Text>