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

package/src/popover/title.tsx

@@ -0,0 +1,50 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useLayoutEffect, useRef } from '@wordpress/element';
+import { Text } from '../text';
+import { usePopoverValidationContext } from './context';
+import type { TitleProps } from './types';
+
+/**
+ * Renders a heading that labels the popover for accessibility.
+ *
+ * **Required** — every popover must include a `Popover.Title`, even if
+ * visually hidden. The rendered element is linked to the popup via
+ * `aria-labelledby`. Uses the `heading-xl` text variant, matching Dialog.
+ *
+ * To visually hide the title while keeping it accessible, wrap it with
+ * `VisuallyHidden` using the `render` prop:
+ *
+ * ```jsx
+ * <VisuallyHidden render={ <Popover.Title /> }>
+ *   Accessible title text
+ * </VisuallyHidden>
+ * ```
+ */
+const Title = forwardRef< HTMLHeadingElement, TitleProps >(
+	function PopoverTitle(
+		{ className, children, render, ...props },
+		forwardedRef
+	) {
+		const validationContext = usePopoverValidationContext();
+		const internalRef = useRef< HTMLHeadingElement >( null );
+		const mergedRef = useMergeRefs( [ internalRef, forwardedRef ] );
+
+		useLayoutEffect( () => {
+			validationContext?.registerTitle( internalRef.current );
+		}, [ validationContext ] );
+
+		return (
+			<Text
+				ref={ mergedRef }
+				variant="heading-xl"
+				render={ <_Popover.Title render={ render } { ...props } /> }
+				className={ className }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);
+
+export { Title };

package/src/popover/trigger.tsx

@@ -0,0 +1,17 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import { forwardRef } from '@wordpress/element';
+import type { TriggerProps } from './types';
+
+/**
+ * Renders a button that toggles the popover popup when clicked.
+ *
+ * Renders as a `<button>` by default. Also supports hover-triggered
+ * popovers via the `openOnHover`, `delay`, and `closeDelay` props.
+ */
+const Trigger = forwardRef< HTMLButtonElement, TriggerProps >(
+	function PopoverTrigger( props, ref ) {
+		return <_Popover.Trigger ref={ ref } { ...props } />;
+	}
+);
+
+export { Trigger };

package/src/popover/types.ts

@@ -0,0 +1,113 @@
+import type { ReactNode } from 'react';
+import type { Popover as _Popover } from '@base-ui/react/popover';
+import type { ComponentProps } from '../utils/types';
+
+export interface RootProps
+	extends Pick<
+		_Popover.Root.Props,
+		'open' | 'onOpenChange' | 'defaultOpen' | 'modal'
+	> {
+	/**
+	 * The popover sub-components (`Popover.Trigger`, `Popover.Popup`, etc.).
+	 */
+	children?: ReactNode;
+}
+
+export interface TriggerProps
+	extends ComponentProps< 'button' >,
+		Pick< _Popover.Trigger.Props, 'openOnHover' | 'delay' | 'closeDelay' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+/**
+ * `Popover.Popup` maps to two Base UI elements internally: the
+ * **Positioner** (outer, handles fixed positioning and z-index) and the
+ * **Popup** (inner, holds content and visual styles).
+ *
+ * `style` and `className` are forwarded to the **Positioner** so that
+ * z-index overrides (`--wp-ui-popover-z-index`) and Base UI CSS variables
+ * (`--available-height`, `--available-width`) work correctly. All other
+ * HTML attributes are forwarded to the inner **Popup** element.
+ */
+export interface PopupProps
+	extends ComponentProps< 'div' >,
+		Pick<
+			_Popover.Positioner.Props,
+			| 'align'
+			| 'alignOffset'
+			| 'anchor'
+			| 'arrowPadding'
+			| 'collisionAvoidance'
+			| 'collisionBoundary'
+			| 'collisionPadding'
+			| 'side'
+			| 'sideOffset'
+			| 'sticky'
+		>,
+		Pick< _Popover.Popup.Props, 'initialFocus' | 'finalFocus' > {
+	/**
+	 * Whether to render a backdrop overlay behind the popover.
+	 *
+	 * Typically used with `modal` to signal that interaction with the rest
+	 * of the page is blocked. The backdrop is a semi-transparent dark overlay.
+	 *
+	 * @default false
+	 */
+	backdrop?: boolean;
+
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * A parent element to render the portal into.
+	 *
+	 * Useful for cross-document rendering, such as rendering a popover
+	 * in a parent document when the trigger is inside an iframe.
+	 */
+	container?: _Popover.Portal.Props[ 'container' ];
+
+	/**
+	 * The visual style variant of the popup.
+	 *
+	 * - `'default'` — standard surface styling with background, padding,
+	 *    border radius, and shadow.
+	 * - `'unstyled'` — no visual treatment; useful as a blank positioning
+	 *    container for fully custom content.
+	 *
+	 * @default 'default'
+	 */
+	variant?: 'default' | 'unstyled';
+}
+
+export interface ArrowProps extends ComponentProps< 'div' > {
+	/**
+	 * Custom arrow visuals to render inside the positioned container.
+	 */
+	children?: ReactNode;
+}
+
+export interface TitleProps extends ComponentProps< 'h2' > {
+	/**
+	 * The title content to be rendered.
+	 */
+	children?: ReactNode;
+}
+
+export interface DescriptionProps extends ComponentProps< 'p' > {
+	/**
+	 * The description content to be rendered.
+	 */
+	children?: ReactNode;
+}
+
+export interface CloseProps extends ComponentProps< 'button' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}

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

@@ -1,4 +1,3 @@
-/* eslint-disable jsx-a11y/heading-has-content */
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Text } from '../index';
 import { Stack } from '../../stack';
@@ -18,6 +17,10 @@ export const Default: Story = {
 	},
 };
 
+/**
+ * Important: Setting the `variant` prop to a `heading` variant will not automatically render a heading element.
+ * Use the `render` prop to render a heading element with the appropriate level.
+ */
 export const AllVariants: Story = {
 	render: () => (
 		<Stack
@@ -65,4 +68,3 @@ export const WithRenderProp: Story = {
 		</Stack>
 	),
 };
-/* eslint-enable jsx-a11y/heading-has-content */

package/src/text/style.module.css

@@ -1,7 +1,13 @@
 @layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
 
 @layer wp-ui-components {
+	.text {
+		margin: 0;
+	}
+
 	.heading-2xl {
+		--_gcd-heading-font-size: var(--wpds-font-size-2xl);
+
 		font-family: var(--wpds-font-family-heading);
 		font-size: var(--wpds-font-size-2xl);
 		line-height: var(--wpds-font-line-height-2xl);
@@ -9,6 +15,8 @@
 	}
 
 	.heading-xl {
+		--_gcd-heading-font-size: var(--wpds-font-size-xl);
+
 		font-family: var(--wpds-font-family-heading);
 		font-size: var(--wpds-font-size-xl);
 		line-height: var(--wpds-font-line-height-md);
@@ -16,6 +24,8 @@
 	}
 
 	.heading-lg {
+		--_gcd-heading-font-size: var(--wpds-font-size-lg);
+
 		font-family: var(--wpds-font-family-heading);
 		font-size: var(--wpds-font-size-lg);
 		line-height: var(--wpds-font-line-height-sm);
@@ -23,6 +33,8 @@
 	}
 
 	.heading-md {
+		--_gcd-heading-font-size: var(--wpds-font-size-md);
+
 		font-family: var(--wpds-font-family-heading);
 		font-size: var(--wpds-font-size-md);
 		line-height: var(--wpds-font-line-height-sm);
@@ -30,6 +42,8 @@
 	}
 
 	.heading-sm {
+		--_gcd-heading-font-size: var(--wpds-font-size-xs);
+
 		font-family: var(--wpds-font-family-heading);
 		font-size: var(--wpds-font-size-xs);
 		line-height: var(--wpds-font-line-height-xs);
@@ -38,6 +52,9 @@
 	}
 
 	.body-xl {
+		--_gcd-p-font-size: var(--wpds-font-size-xl);
+		--_gcd-p-line-height: var(--wpds-font-line-height-xl);
+
 		font-family: var(--wpds-font-family-body);
 		font-size: var(--wpds-font-size-xl);
 		line-height: var(--wpds-font-line-height-xl);
@@ -45,6 +62,9 @@
 	}
 
 	.body-lg {
+		--_gcd-p-font-size: var(--wpds-font-size-lg);
+		--_gcd-p-line-height: var(--wpds-font-line-height-md);
+
 		font-family: var(--wpds-font-family-body);
 		font-size: var(--wpds-font-size-lg);
 		line-height: var(--wpds-font-line-height-md);
@@ -52,6 +72,9 @@
 	}
 
 	.body-md {
+		--_gcd-p-font-size: var(--wpds-font-size-md);
+		--_gcd-p-line-height: var(--wpds-font-line-height-sm);
+
 		font-family: var(--wpds-font-family-body);
 		font-size: var(--wpds-font-size-md);
 		line-height: var(--wpds-font-line-height-sm);
@@ -59,6 +82,9 @@
 	}
 
 	.body-sm {
+		--_gcd-p-font-size: var(--wpds-font-size-sm);
+		--_gcd-p-line-height: var(--wpds-font-line-height-xs);
+
 		font-family: var(--wpds-font-family-body);
 		font-size: var(--wpds-font-size-sm);
 		line-height: var(--wpds-font-line-height-xs);

package/src/text/test/index.test.tsx

@@ -34,10 +34,7 @@ describe( 'Text', () => {
 	} );
 
 	it( 'supports the render prop', () => {
-		render(
-			// eslint-disable-next-line jsx-a11y/heading-has-content
-			<Text render={ <h2 /> }>Section title</Text>
-		);
+		render( <Text render={ <h2 /> }>Section title</Text> );
 
 		expect(
 			screen.getByRole( 'heading', { level: 2, name: 'Section title' } )

package/src/text/text.tsx

@@ -3,6 +3,7 @@ import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { type TextProps } from './types';
 import styles from './style.module.css';
+import defenseStyles from '../utils/css/global-css-defense.module.css';
 
 /**
  * A text component for rendering content with predefined typographic variants.
@@ -17,7 +18,13 @@ export const Text = forwardRef< HTMLSpanElement, TextProps >( function Text(
 		defaultTagName: 'span',
 		ref,
 		props: mergeProps< 'span' >( props, {
-			className: clsx( styles[ variant ], className ),
+			className: clsx(
+				styles.text,
+				variant.startsWith( 'heading-' ) && defenseStyles.heading,
+				variant.startsWith( 'body-' ) && defenseStyles.p,
+				styles[ variant ],
+				className
+			),
 		} ),
 	} );
 

package/src/utils/css/field.module.css

@@ -18,7 +18,10 @@
 	}
 
 	.description {
-		margin: 0;
+		--_gcd-p-font-size: var(--wpds-font-size-sm);
+		--_gcd-p-line-height: var(--wpds-font-line-height-xs);
+		--_gcd-p-margin: 0;
+
 		font-family: var(--wpds-font-family-body);
 		font-size: var(--wpds-font-size-sm);
 		line-height: var(--wpds-font-line-height-xs);

package/src/utils/css/focus.module.css

@@ -9,14 +9,14 @@
 	.outset-ring--focus-within-visible,
 	.outset-ring--focus-parent-visible {
 		@media not ( prefers-reduced-motion ) {
+			--_gcd-a-transition: outline 0.1s ease-out;
+
 			transition: outline 0.1s ease-out;
 		}
 
 		/* Outline width must be kept at 0 even with a transparent color,
 		or else the outline will be visible in forced-colors mode. */
-		outline-width: 0;
-		outline-style: solid;
-		outline-color: transparent;
+		outline: 0 solid transparent;
 		outline-offset: 1px;
 	}
 
@@ -27,7 +27,9 @@
 	.outset-ring--focus-within-except-active:focus-within:not(:has(:active)),
 	.outset-ring--focus-within-visible:focus-within:has(:focus-visible),
 	:focus-visible .outset-ring--focus-parent-visible {
-		outline-width: var(--wpds-border-width-focus);
-		outline-color: var(--wpds-color-stroke-focus-brand);
+		--_gcd-a-outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand);
+		--_gcd-div-outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand);
+
+		outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand);
 	}
 }

package/src/utils/css/global-css-defense.module.css

@@ -0,0 +1,117 @@
+/*
+ * Unlayered defense against wp-admin global CSS (common.css, forms.css).
+ *
+ * CSS cascade layers always lose to unlayered styles, so @wordpress/ui's
+ * layered component styles get overridden by wp-admin's broad bare-element
+ * selectors. This file provides unlayered, class-scoped defenses that
+ * restore control to the component.
+ *
+ * Mechanism (custom property bridge):
+ *   .input { font-size: var(--_gcd-input-font-size, inherit); }
+ *
+ * - The class selector beats admin bare-element selectors in specificity.
+ * - Each property reads a custom property. The fallback values are what
+ *   makes sense for @wordpress/ui, to minimize the number of overrides
+ *   in each individual component stylesheet.
+ * - Component CSS modules only need to define the custom properties for
+ *   the specific properties they want to override.
+ * - Custom property definitions aren't suppressed by cascade layers, so the
+ *   layered value propagates through to the unlayered declaration.
+ *
+ * Usage: apply the element-specific class directly to each element that
+ * needs defense (e.g. defenseStyles.input on an <input>).
+ */
+
+/*
+ * ==========================================================================
+ * forms.css defense - https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-admin/css/forms.css
+ * ==========================================================================
+ */
+
+.button {
+	box-sizing: var(--_gcd-button-box-sizing, border-box);
+	font-family: var(--_gcd-button-font-family, inherit);
+	font-size: var(--_gcd-button-font-size, inherit);
+	font-weight: var(--_gcd-button-font-weight, inherit);
+}
+
+.input {
+	box-sizing: var(--_gcd-input-box-sizing, border-box);
+	font-family: var(--_gcd-input-font-family, inherit);
+	font-size: var(--_gcd-input-font-size, inherit);
+	font-weight: var(--_gcd-input-font-weight, inherit);
+	margin: var(--_gcd-input-margin, 0);
+
+	/* Also targets textarea elements, which the `Input` primitive can render as. We combine these textarea defenses
+	   into the input defenses to minimize the number of tokens, but they should be split if it ever becomes necessary. */
+	&:is(textarea, [type="text"], [type="password"], [type="color"], [type="date"], [type="datetime"], [type="datetime-local"], [type="email"], [type="month"], [type="number"], [type="search"], [type="tel"], [type="time"], [type="url"], [type="week"]) {
+		box-shadow: var(--_gcd-input-box-shadow, 0 0 0 transparent);
+		border-radius: var(--_gcd-input-border-radius, 0);
+		border: var(--_gcd-input-border, none);
+		background-color: var(--_gcd-input-background-color, transparent);
+		color: var(--_gcd-input-color, var(--wpds-color-fg-interactive-neutral));
+
+		&:focus {
+			border-color: var(--_gcd-input-border-color-focus, var(--wp-admin-theme-color));
+			box-shadow: var(--_gcd-input-box-shadow-focus, none);
+			outline: var(--_gcd-input-outline-focus, none);
+		}
+
+		&:disabled {
+			background: var(--_gcd-input-background-disabled, transparent);
+			border-color: var(--_gcd-input-border-color-disabled, transparent);
+			box-shadow: var(--_gcd-input-box-shadow-disabled, none);
+			color: var(--_gcd-input-color-disabled, var(--wpds-color-fg-interactive-neutral-disabled));
+		}
+
+		&::placeholder {
+			color: var(--_gcd-input-placeholder-color, var(--wpds-color-fg-interactive-neutral-disabled));
+		}
+	}
+
+	&:is(textarea, [type="text"], [type="password"], [type="date"], [type="datetime"], [type="datetime-local"], [type="email"], [type="month"], [type="number"], [type="search"], [type="tel"], [type="time"], [type="url"], [type="week"]) {
+		padding: var(--_gcd-input-padding, 0);
+		line-height: var(--_gcd-input-line-height, inherit);
+		min-height: var(--_gcd-input-min-height, auto);
+	}
+}
+
+.textarea {
+	box-sizing: var(--_gcd-textarea-box-sizing, border-box);
+	overflow: var(--_gcd-textarea-overflow, auto);
+	resize: var(--_gcd-textarea-resize, block);
+}
+
+/*
+ * ==========================================================================
+ * common.css defense - https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-admin/css/common.css
+ * ==========================================================================
+ */
+
+.div {
+	outline: var(--_gcd-div-outline, 0 solid transparent);
+}
+
+/* Narrowed down to p elements only, to support element multiplicity of Text component. */
+p.p {
+	font-size: var(--_gcd-p-font-size, 13px);
+	line-height: var(--_gcd-p-line-height, 1.5);
+	margin: var(--_gcd-p-margin, 0);
+}
+
+/* Narrowed down to h[1-6] elements only, to support element multiplicity of Text component. */
+:is(h1, h2, h3, h4, h5, h6).heading {
+	color: var(--_gcd-heading-color, var(--wpds-color-fg-content-neutral));
+	font-size: var(--_gcd-heading-font-size, inherit);
+	font-weight: var(--_gcd-heading-font-weight, var(--wpds-font-weight-medium));
+	margin: var(--_gcd-heading-margin, 0);
+}
+
+.a,
+.a:is(:hover, :focus, :active) {
+	outline: var(--_gcd-a-outline, 0 solid transparent);
+	color: var(--_gcd-a-color, inherit);
+	box-shadow: var(--_gcd-a-box-shadow, none);
+	border-radius: var(--_gcd-a-border-radius, 0);
+	transition: var(--_gcd-a-transition, none);
+}

package/src/utils/use-deprioritized-initial-focus.ts

@@ -1,12 +1,13 @@
-import type { Dialog as _Dialog } from '@base-ui/react/dialog';
+import type { Popover as _Popover } from '@base-ui/react/popover';
 import { useMemo, useRef } from '@wordpress/element';
 import { tabbable } from 'tabbable';
 
 /**
- * Derived from Base UI's `Dialog.Popup.Props['initialFocus']`.
- * The same type is shared by all Base UI overlay popups (Dialog, Popover, etc.).
+ * The `initialFocus` type shared by Base UI overlay popups (Dialog, Popover,
+ * AlertDialog, etc.). We derive it from `Popover.Popup.Props` here, but it
+ * is identical across all overlay components.
  */
-type InitialFocus = _Dialog.Popup.Props[ 'initialFocus' ];
+type InitialFocus = _Popover.Popup.Props[ 'initialFocus' ];
 
 /**
  * Options matching Base UI's internal tabbable configuration.