@wordpress/ui 0.11.1-next.v.202604091042.0 → 0.12.0

package/src/form/primitives/field/label.tsx

@@ -10,7 +10,7 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 		{ className, hideFromVision, variant, ...restProps },
 		ref
 	) {
-		return (
+		const label = (
 			<_Field.Label
 				ref={ ref }
 				className={ clsx(
@@ -18,12 +18,16 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 					variant && fieldStyles[ `is-${ variant }` ],
 					className
 				) }
-				{ ...( hideFromVision && {
-					render: <VisuallyHidden />,
-					nativeLabel: false,
-				} ) }
 				{ ...restProps }
 			/>
 		);
+
+		// VisuallyHidden is the host so that _Field.Label's semantic
+		// element is preserved. See VisuallyHidden docs for details.
+		if ( hideFromVision ) {
+			return <VisuallyHidden render={ label } />;
+		}
+
+		return label;
 	}
 );

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

@@ -5,7 +5,7 @@ import resetStyles from '../../../utils/css/resets.module.css';
 import type { FieldRootProps } from './types';
 import { Stack } from '../../../stack';
 
-const defaultRender = ( props: React.ComponentProps< typeof Stack > ) => (
+const DEFAULT_RENDER = ( props: React.ComponentProps< typeof Stack > ) => (
 	<Stack { ...props } direction="column" gap="sm" />
 );
 
@@ -19,7 +19,7 @@ const defaultRender = ( props: React.ComponentProps< typeof Stack > ) => (
  * accessible labeling. See examples for how to associate the label in different cases.
  */
 export const Root = forwardRef< HTMLDivElement, FieldRootProps >( function Root(
-	{ className, render = defaultRender, ...restProps },
+	{ className, render = DEFAULT_RENDER, ...restProps },
 	ref
 ) {
 	return (

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

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId } from '@wordpress/element';
-import { Field } from '../../../..';
+import * as Field from '../';
 import { DETAILS_EXAMPLE } from '../../../stories/shared';
 
 const meta: Meta< typeof Field.Root > = {

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

@@ -47,6 +47,17 @@ describe( 'Field', () => {
 		).toBeVisible();
 	} );
 
+	it( 'preserves the native label element when hideFromVision is enabled', () => {
+		render(
+			<Field.Root>
+				<Field.Label hideFromVision>Field Label</Field.Label>
+				<Field.Control render={ <input /> } />
+			</Field.Root>
+		);
+
+		expect( screen.getByText( 'Field Label' ).tagName ).toBe( 'LABEL' );
+	} );
+
 	it( 'renders details with a semantically associated description for the control', () => {
 		render(
 			<Field.Root>

package/src/form/primitives/fieldset/legend.tsx

@@ -10,15 +10,20 @@ export const FieldsetLegend = forwardRef< HTMLDivElement, FieldsetLegendProps >(
 		{ className, hideFromVision, ...restProps },
 		ref
 	) {
-		return (
+		const legend = (
 			<_Fieldset.Legend
 				ref={ ref }
 				className={ clsx( fieldStyles.label, className ) }
-				{ ...( hideFromVision && {
-					render: <VisuallyHidden />,
-				} ) }
 				{ ...restProps }
 			/>
 		);
+
+		// VisuallyHidden is the host so that _Fieldset.Legend's semantic
+		// element is preserved. See VisuallyHidden docs for details.
+		if ( hideFromVision ) {
+			return <VisuallyHidden render={ legend } />;
+		}
+
+		return legend;
 	}
 );

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

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Fieldset } from '../../../..';
+import * as Fieldset from '../';
 import { DETAILS_EXAMPLE } from '../../../stories/shared';
 
 const meta: Meta< typeof Fieldset.Root > = {

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

@@ -43,6 +43,28 @@ describe( 'Fieldset', () => {
 		).toBeVisible();
 	} );
 
+	it( 'preserves the legend element type when hideFromVision is enabled', () => {
+		const { rerender } = render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		const tagWithout = screen.getByText( 'Choose your options' ).tagName;
+
+		rerender(
+			<Fieldset.Root>
+				<Fieldset.Legend hideFromVision>
+					Choose your options
+				</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		expect( screen.getByText( 'Choose your options' ).tagName ).toBe(
+			tagWithout
+		);
+	} );
+
 	it( 'accessibly associates description when Fieldset.Description is present', () => {
 		render(
 			<Fieldset.Root>

package/src/form/primitives/index.ts

@@ -1,3 +1,4 @@
+export * as Autocomplete from './autocomplete';
 export * as Field from './field';
 export * as Fieldset from './fieldset';
 export { Input } from './input';

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/input-layout/style.module.css

@@ -11,13 +11,13 @@
 		border-style: solid;
 		border-color: var(--wpds-color-stroke-interactive-neutral);
 		border-radius: var(--wpds-border-radius-sm);
-		font-family: var(--wpds-font-family-body);
-		font-size: max(var(--wpds-font-size-md), 16px); /* avoid mobile zoom */
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: max(var(--wpds-typography-font-size-md), 16px); /* avoid mobile zoom */
 		line-height: 1;
 		color: var(--wpds-color-fg-interactive-neutral);
 
 		@media (min-width: 600px) {
-			font-size: var(--wpds-font-size-md);
+			font-size: var(--wpds-typography-font-size-md);
 		}
 
 		&.is-size-compact {

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,40 +18,38 @@ const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
-	function Popup( { className, children, style, ...restProps }, ref ) {
-		return (
-			<_Select.Portal>
-				<_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

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
 import * as Select from '../index';
@@ -30,4 +30,67 @@ describe( 'Select', () => {
 		expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
 		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
+
+	describe( 'portal', () => {
+		it( 'should render inside the portal container when a custom target is provided', async () => {
+			const user = userEvent.setup();
+			const containerRef = createRef< HTMLDivElement >();
+
+			render(
+				<div data-testid="wrapper">
+					<Select.Root>
+						<Select.Trigger />
+						<div
+							ref={ containerRef }
+							data-testid="custom-container"
+						/>
+						<Select.Popup
+							portal={
+								<Select.Portal container={ containerRef } />
+							}
+						>
+							<Select.Item value="Item 1" />
+						</Select.Popup>
+					</Select.Root>
+				</div>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			expect( screen.getByTestId( 'custom-container' ) ).toContainElement(
+				item
+			);
+		} );
+
+		it( 'should render with a portal by default', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<div data-testid="wrapper">
+					<Select.Root>
+						<Select.Trigger />
+						<Select.Popup>
+							<Select.Item value="Item 1" />
+						</Select.Popup>
+					</Select.Root>
+				</div>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			expect( screen.getByTestId( 'wrapper' ) ).not.toContainElement(
+				item
+			);
+		} );
+	} );
 } );

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

@@ -1,13 +1,18 @@
 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 >,
 	'multiple'
 >;
 
-export type SelectTriggerProps = Omit< _Select.Trigger.Props, 'children' > & {
+export type SelectTriggerProps = ComponentProps< typeof _Select.Trigger > & {
 	/**
 	 * The size of the trigger.
 	 *
@@ -27,11 +32,23 @@ export type SelectTriggerProps = Omit< _Select.Trigger.Props, 'children' > & {
 	children?: _Select.Value.Props[ 'children' ];
 };
 
-export type SelectPopupProps = _Select.Popup.Props;
+export type SelectPopupProps = ComponentProps< typeof _Select.Popup > & {
+	/**
+	 * The content to be rendered inside the popup.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * 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.
+	 */
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
+};
 
 export type SelectItemProps = Omit<
-	_Select.Item.Props,
-	'children' | 'value'
+	ComponentProps< typeof _Select.Item >,
+	'value'
 > & {
 	/**
 	 * A unique value that identifies this select item.

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-font-weight-regular);
+		font-weight: var(--wpds-typography-font-weight-regular);
+		text-decoration: none;
 	}
 
 	.link-icon::after {