@wordpress/ui 0.9.1-next.v.202603161435.0 → 0.11.0

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

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { InputLayout } from '../../../..';
+import { copy } from '@wordpress/icons';
+import { IconButton, InputLayout } from '../../../..';
 
 const meta: Meta< typeof InputLayout > = {
 	title: 'Design System/Components/Form/Primitives/InputLayout',
@@ -50,6 +51,26 @@ export const WithPaddedPrefix: Story = {
 	},
 };
 
+/**
+ * The `padding="minimal"` setting on `InputLayout.Slot` will work best when
+ * the slot content is a button or icon.
+ */
+export const WithSuffixControl: Story = {
+	args: {
+		children: <div style={ { flex: 1 } } />,
+		suffix: (
+			<InputLayout.Slot padding="minimal">
+				<IconButton
+					size="small"
+					variant="minimal"
+					icon={ copy }
+					label="Copy"
+				/>
+			</InputLayout.Slot>
+		),
+	},
+};
+
 export const Compact: Story = {
 	args: {
 		size: 'compact',

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/popup.tsx

@@ -16,9 +16,12 @@ const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
-	function Popup( { className, children, style, ...restProps }, ref ) {
+	function Popup(
+		{ className, container, children, style, ...restProps },
+		ref
+	) {
 		return (
-			<_Select.Portal>
+			<_Select.Portal container={ container }>
 				<_Select.Positioner
 					{ ...ITEM_POPUP_POSITIONER_PROPS }
 					alignItemWithTrigger={ false }

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,63 @@ describe( 'Select', () => {
 		expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
 		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
+
+	describe( 'container', () => {
+		it( 'should render inside the container when 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 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,4 +1,5 @@
 import type { Select as _Select } from '@base-ui/react/select';
+import type { ComponentProps } from '../../../utils/types';
 import type { InputLayoutProps } from '../input-layout/types';
 
 // The second type parameter is the `multiple` flag (currently disabled).
@@ -7,7 +8,7 @@ export type SelectRootProps = Omit<
 	'multiple'
 >;
 
-export type SelectTriggerProps = Omit< _Select.Trigger.Props, 'children' > & {
+export type SelectTriggerProps = ComponentProps< typeof _Select.Trigger > & {
 	/**
 	 * The size of the trigger.
 	 *
@@ -27,11 +28,20 @@ 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;
+	/**
+	 * A parent element to render the portal into.
+	 */
+	container?: _Select.Portal.Props[ 'container' ];
+};
 
 export type SelectItemProps = Omit<
-	_Select.Item.Props,
-	'children' | 'value'
+	ComponentProps< typeof _Select.Item >,
+	'value'
 > & {
 	/**
 	 * A unique value that identifies this select item.

package/src/form/primitives/stories/overview.mdx

@@ -0,0 +1,15 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+# Form Primitives
+
+<Meta title="Design System/Components/Form/Primitives" name="Overview" />
+
+These form primitives are the low-level building blocks for form-related components. Outside of rare, special use cases, a normal developer should not need to use these primitives directly.
+
+## When to use these primitives
+
+1. First check if there is a higher-level `*Control` component that meets your needs, either in this package, or if not, in [`@wordpress/components`](https://wordpress.github.io/gutenberg/?path=/docs/components-introduction--docs). Also consider using [`DataForm`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dataviews/#dataform), an even higher-level abstraction.
+2. If not, discuss with your designer whether the design can be altered to not require these primitives.
+3. If not, then these primitives are the next best option. Keep in mind that you are responsible for ensuring that your implementation is accessible, and adheres to Design System guidelines.
+
+Feel free to reach out to the `#design-system` channel on the [Make WordPress Slack](https://make.wordpress.org/chat/) for guidance.

package/src/form/primitives/textarea/textarea.tsx

@@ -4,12 +4,13 @@ import { cloneElement, forwardRef } from '@wordpress/element';
 import styles from './style.module.css';
 import type { TextareaProps } from './types';
 import { Input } from '../input';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 
 const wrappedRender = (
 	render: NonNullable< TextareaProps[ 'render' ] >,
 	restProps: TextareaProps & { ref: React.Ref< HTMLTextAreaElement > }
 ) => {
-	return function Render(
+	return function textareaRender(
 		props: React.HTMLAttributes< HTMLTextAreaElement >
 	) {
 		return typeof render === 'function'
@@ -39,7 +40,15 @@ export const Textarea = forwardRef< HTMLTextAreaElement, TextareaProps >(
 				style={ style }
 				render={ wrappedRender(
 					render || ( ( props ) => <textarea { ...props } /> ),
-					{ className: styles.textarea, ref, rows, ...restProps }
+					{
+						className: clsx(
+							defenseStyles.textarea,
+							styles.textarea
+						),
+						ref,
+						rows,
+						...restProps,
+					}
 				) }
 				value={ value }
 				defaultValue={ defaultValue }

package/src/form/stories/shared.tsx

@@ -0,0 +1,21 @@
+import { Link } from '../..';
+
+export const WITH_DETAILS_DESCRIPTION = `\
+To add rich content (such as links) to the description, use the \`details\` prop.
+
+Although this content is not associated with the field using direct semantics,
+it is made discoverable to screen reader users via a visually hidden description,
+alerting them to the presence of additional information below.
+
+**Important:** If the content only includes plain text, use \`description\` instead,
+so the readout is not unnecessarily verbose for screen reader users.`;
+
+export const DETAILS_EXAMPLE = (
+	<>
+		Details can include{ ' ' }
+		<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
+			links to more information
+		</Link>{ ' ' }
+		and other semantic elements.
+	</>
+);

package/src/form/types.ts

@@ -0,0 +1,34 @@
+import type { Field } from './primitives';
+
+export type ControlProps = {
+	/**
+	 * The accessible label. All controls must be labeled.
+	 */
+	label: React.ComponentProps< typeof Field.Label >[ 'children' ];
+	/**
+	 * The accessible description, associated using `aria-describedby`.
+	 *
+	 * For screen reader accessibility, this should only contain plain text,
+	 * and no semantics such as links.
+	 */
+	description?: React.ComponentProps<
+		typeof Field.Description
+	>[ 'children' ];
+	/**
+	 * Additional information about the field, which unlike a normal description,
+	 * can include links and other semantic elements.
+	 *
+	 * Do not use this prop when the content is only plain text;
+	 * use `description` instead.
+	 */
+	details?: React.ComponentProps< typeof Field.Details >[ 'children' ];
+	/**
+	 * Whether to visually hide the label while keeping it accessible
+	 * to screen readers.
+	 *
+	 * @default false
+	 */
+	hideLabelFromVision?: React.ComponentProps<
+		typeof Field.Label
+	>[ 'hideFromVision' ];
+};

package/src/index.ts

@@ -3,12 +3,15 @@ export * from './button';
 export * as Card from './card';
 export * as Collapsible from './collapsible';
 export * as CollapsibleCard from './collapsible-card';
+export * as AlertDialog from './alert-dialog';
 export * as Dialog from './dialog';
-export * from './form/primitives';
+export * as EmptyState from './empty-state';
+export * from './form';
 export * from './icon';
 export * from './icon-button';
 export * from './link';
 export * as Notice from './notice';
+export * as Popover from './popover';
 export * from './stack';
 export * as Tabs from './tabs';
 export * from './text';

package/src/link/link.tsx

@@ -6,6 +6,7 @@ import { type LinkProps } from './types';
 import resetStyles from '../utils/css/resets.module.css';
 import focusStyles from '../utils/css/focus.module.css';
 import styles from './style.module.css';
+import defenseStyles from '../utils/css/global-css-defense.module.css';
 
 /**
  * A styled anchor element with support for semantic color tones and an
@@ -39,6 +40,7 @@ export const Link = forwardRef< HTMLAnchorElement, LinkProps >( function Link(
 		ref,
 		props: mergeProps< 'a' >( props, {
 			className: clsx(
+				defenseStyles.a,
 				resetStyles[ 'box-sizing' ],
 				focusStyles[ 'outset-ring--focus' ],
 				variant !== 'unstyled' && styles.link,

package/src/link/style.module.css

@@ -9,28 +9,38 @@
 	/* Brand tone */
 	.is-brand,
 	.is-brand:visited {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-brand);
+
 		color: var(--wpds-color-fg-interactive-brand);
 	}
 
 	.is-brand:hover,
 	.is-brand:active {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-brand-active);
+
 		color: var(--wpds-color-fg-interactive-brand-active);
 	}
 
 	/* Neutral tone */
 	.is-neutral,
 	.is-neutral:visited {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-neutral);
+
 		color: var(--wpds-color-fg-interactive-neutral);
 		text-decoration-color: var(--wpds-color-stroke-interactive-neutral);
 	}
 
 	.is-neutral:hover,
 	.is-neutral:active {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-neutral-active);
+
 		color: var(--wpds-color-fg-interactive-neutral-active);
 	}
 
 	/* Unstyled variant */
 	.is-unstyled {
+		--_gcd-a-color: inherit;
+
 		color: inherit;
 		text-decoration: none;
 	}
@@ -55,7 +65,7 @@
 
 	.link-icon {
 		margin-inline-start: var(--wpds-dimension-padding-xs);
-		font-weight: var(--wpds-font-weight-regular);
+		font-weight: var(--wpds-typography-font-weight-regular);
 	}
 
 	.link-icon::after {

package/src/notice/index.ts

@@ -15,5 +15,3 @@ export {
 	ActionButton,
 	ActionLink,
 };
-
-export type { NoticeIntent } from './types';

package/src/notice/style.module.css

@@ -3,7 +3,7 @@
 @layer wp-ui-components {
 	.notice {
 		--icon-height: 24px;
-		--text-vertical-padding: calc((var(--icon-height) - var(--wpds-font-line-height-sm)) / 2);
+		--text-vertical-padding: calc((var(--icon-height) - var(--wpds-typography-line-height-sm)) / 2);
 
 		--wp-ui-notice-background-color: var(--wpds-color-bg-surface-neutral-weak);
 		--wp-ui-notice-border-color: var(--wpds-color-stroke-surface-neutral);
@@ -64,10 +64,10 @@
 
 	.action-link {
 		flex-shrink: 0;
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-md);
-		font-weight: var(--wpds-font-weight-regular);
-		line-height: var(--wpds-font-line-height-sm);
+		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 */
@@ -115,7 +115,7 @@
 		--wp-ui-notice-decorative-icon-color: var(--wpds-color-fg-content-error-weak);
 	}
 
-	/* TODO: Replace 320px with a measure token from the Theme package. */
+	/* Matches --wpds-dimension-surface-width-sm (container queries don't support custom properties). */
 	@container (max-width: 320px) {
 		.notice:has(.title) .description,
 		.notice:has(.title) .actions {

package/src/popover/arrow.tsx

@@ -0,0 +1,49 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { ArrowProps } from './types';
+
+function DefaultArrowSvg( props: React.ComponentProps< 'svg' > ) {
+	return (
+		<svg
+			width="20"
+			height="10"
+			viewBox="0 0 20 10"
+			fill="none"
+			{ ...props }
+		>
+			<path
+				d="M20 10H0V8h1.465a4 4 0 0 0 2.676-1.027l5.19-4.388c.378-.341.96-.341 1.338 0l5.19 4.388A4 4 0 0 0 18.535 8H20z"
+				className={ styles[ 'arrow-fill' ] }
+			/>
+			<path
+				d="M10 3.097 4.81 7.486A5 5 0 0 1 1.465 8.77H0V8h1.465a4 4 0 0 0 2.676-1.027l5.19-4.388c.378-.341.96-.341 1.338 0l5.19 4.388A4 4 0 0 0 18.535 8H20v.77h-1.465a5 5 0 0 1-3.345-1.284z"
+				className={ styles[ 'arrow-stroke' ] }
+			/>
+		</svg>
+	);
+}
+
+/**
+ * Renders an optional arrow element that points toward the anchor.
+ *
+ * Must be placed inside `Popover.Popup`. The arrow automatically rotates
+ * to match the current placement side.
+ */
+const Arrow = forwardRef< HTMLDivElement, ArrowProps >( function PopoverArrow(
+	{ children, className, ...props },
+	ref
+) {
+	return (
+		<_Popover.Arrow
+			ref={ ref }
+			className={ clsx( styles.arrow, className ) }
+			{ ...props }
+		>
+			{ children ?? <DefaultArrowSvg /> }
+		</_Popover.Arrow>
+	);
+} );
+
+export { Arrow };

package/src/popover/close.tsx

@@ -0,0 +1,24 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import { forwardRef } from '@wordpress/element';
+import type { CloseProps } from './types';
+
+/**
+ * Renders a button that closes the popover when clicked.
+ *
+ * When the popover opens, initial focus skips this button in favor of
+ * the first interactive element inside the popup (unless `initialFocus`
+ * on `Popover.Popup` overrides this behavior).
+ */
+const Close = forwardRef< HTMLButtonElement, CloseProps >(
+	function PopoverClose( props, ref ) {
+		return (
+			<_Popover.Close
+				ref={ ref }
+				data-wp-ui-popover-close=""
+				{ ...props }
+			/>
+		);
+	}
+);
+
+export { Close };

package/src/popover/context.tsx

@@ -0,0 +1,100 @@
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+} from '@wordpress/element';
+
+/**
+ * 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;
+}
+
+/**
+ * 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 }</>;
+}
+
+/**
+ * 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;

package/src/popover/description.tsx

@@ -0,0 +1,29 @@
+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 ) {
+		return (
+			<Text
+				ref={ ref }
+				variant="body-md"
+				render={ <_Popover.Description { ...props } /> }
+				className={ clsx( styles.description, className ) }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);
+
+export { Description };

package/src/popover/index.ts

@@ -0,0 +1,9 @@
+import { Arrow } from './arrow';
+import { Close } from './close';
+import { Description } from './description';
+import { Popup } from './popup';
+import { Root } from './root';
+import { Title } from './title';
+import { Trigger } from './trigger';
+
+export { Arrow, Close, Description, Popup, Root, Title, Trigger };