@wordpress/ui 0.10.0 → 0.11.0

package/src/tooltip/test/index.test.tsx

@@ -84,4 +84,65 @@ describe( 'Tooltip', () => {
 			screen.queryByText( 'Tooltip content' )
 		).not.toBeInTheDocument();
 	} );
+
+	describe( 'container', () => {
+		it( 'should render inside the container when provided', async () => {
+			const user = userEvent.setup();
+			const containerRef = createRef< HTMLDivElement >();
+
+			render(
+				<TestProvider>
+					<div data-testid="wrapper">
+						<Tooltip.Root>
+							<Tooltip.Trigger>Hover me</Tooltip.Trigger>
+							<div
+								ref={ containerRef }
+								data-testid="custom-container"
+							/>
+							<Tooltip.Popup container={ containerRef }>
+								Tooltip content
+							</Tooltip.Popup>
+						</Tooltip.Root>
+					</div>
+				</TestProvider>
+			);
+
+			await user.hover(
+				screen.getByRole( 'button', { name: 'Hover me' } )
+			);
+
+			const content = await screen.findByText( 'Tooltip content' );
+			expect( content ).toBeVisible();
+
+			expect( screen.getByTestId( 'custom-container' ) ).toContainElement(
+				content
+			);
+		} );
+
+		it( 'should render with a portal by default', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<TestProvider>
+					<div data-testid="wrapper">
+						<Tooltip.Root>
+							<Tooltip.Trigger>Hover me</Tooltip.Trigger>
+							<Tooltip.Popup>Tooltip content</Tooltip.Popup>
+						</Tooltip.Root>
+					</div>
+				</TestProvider>
+			);
+
+			await user.hover(
+				screen.getByRole( 'button', { name: 'Hover me' } )
+			);
+
+			const content = await screen.findByText( 'Tooltip content' );
+			expect( content ).toBeVisible();
+
+			expect( screen.getByTestId( 'wrapper' ) ).not.toContainElement(
+				content
+			);
+		} );
+	} );
 } );

package/src/tooltip/types.ts

@@ -23,4 +23,9 @@ export interface PopupProps
 	 * The content to be rendered inside the component.
 	 */
 	children?: ReactNode;
+
+	/**
+	 * A parent element to render the portal into.
+	 */
+	container?: Tooltip.Portal.Props[ 'container' ];
 }

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

@@ -2,26 +2,29 @@
 
 @layer wp-ui-utilities {
 	.label {
-		--wp-ui-field-label-line-height: var(--wpds-font-line-height-xs);
+		--wp-ui-field-label-line-height: var(--wpds-typography-line-height-xs);
 
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-xs);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-xs);
 		line-height: var(--wp-ui-field-label-line-height);
-		font-weight: var(--wpds-font-weight-medium);
+		font-weight: var(--wpds-typography-font-weight-medium);
 		text-transform: uppercase;
 		color: var(--wpds-color-fg-content-neutral);
 
 		&.is-plain {
-			font-size: var(--wpds-font-size-md);
+			font-size: var(--wpds-typography-font-size-md);
 			text-transform: none;
 		}
 	}
 
 	.description {
-		margin: 0;
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-sm);
-		line-height: var(--wpds-font-line-height-xs);
+		--_gcd-p-font-size: var(--wpds-typography-font-size-sm);
+		--_gcd-p-line-height: var(--wpds-typography-line-height-xs);
+		--_gcd-p-margin: 0;
+
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-sm);
+		line-height: var(--wpds-typography-line-height-xs);
 		color: var(--wpds-color-fg-content-neutral-weak);
 	}
 }

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-typography-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/css/item-popup.module.css

@@ -16,8 +16,8 @@
 		border: 1px solid var(--wpds-color-stroke-surface-neutral);
 		box-shadow: var(--wpds-elevation-md);
 		background-color: var(--wpds-color-bg-surface-neutral-strong);
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-md);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
 		line-height: 1.4;
 		color: var(--wpds-color-fg-interactive-neutral);
 	}

package/src/utils/types.ts

@@ -14,13 +14,18 @@ type ComponentRenderFn< Props > = (
 
 export type ComponentProps< E extends ElementType > = Omit<
 	ComponentPropsWithoutRef< E >,
-	'className' | 'children' | 'render'
+	'className' | 'children' | 'render' | 'style'
 > & {
 	/**
-	 * CSS class name to apply to the component.
+	 * CSS class name to apply to the element.
 	 */
 	className?: string;
 
+	/**
+	 * CSS style to apply to the element.
+	 */
+	style?: React.CSSProperties;
+
 	/**
 	 * Replaces the component's default HTML element using a given React
 	 * element, or a function that returns a React element.

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.

package/src/visually-hidden/stories/index.story.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useId } from '@wordpress/element';
 import { VisuallyHidden } from '../';
 
 const meta: Meta< typeof VisuallyHidden > = {
@@ -20,3 +21,27 @@ export const Default: Story = {
 		</>
 	),
 };
+
+/**
+ * Use the `render` prop to change the underlying HTML element.
+ * By default, `VisuallyHidden` renders a `<div>`. Here it renders
+ * a `<label>` instead, keeping the native label–input association
+ * while hiding the label text visually.
+ */
+export const WithCustomElement: Story = {
+	render: function WithCustomElementStory() {
+		const inputId = useId();
+		return (
+			<>
+				{ /* eslint-disable-next-line jsx-a11y/label-has-associated-control */ }
+				<VisuallyHidden render={ <label htmlFor={ inputId } /> }>
+					Accessible label
+				</VisuallyHidden>
+				<input
+					id={ inputId }
+					placeholder="This input has a visually hidden label"
+				/>
+			</>
+		);
+	},
+};

package/src/visually-hidden/visually-hidden.tsx

@@ -6,6 +6,40 @@ import styles from './style.module.css';
 /**
  * Visually hides content while keeping it accessible to screen readers.
  * Useful when providing context that's only meaningful to assistive technology.
+ *
+ * Renders a `<div>` by default. Use the `render` prop to swap the
+ * underlying element while preserving the visually-hidden behavior.
+ *
+ * ## Composing with other components
+ *
+ * When composing with another component that uses the `render` prop
+ * pattern, there are two directions — and they produce different results.
+ *
+ * Most of the time you'll want `VisuallyHidden` as the **host** (outer
+ * component) and pass the other component via `render`. This keeps the
+ * other component's HTML element and semantics intact, while
+ * `VisuallyHidden` only adds its hiding styles:
+ *
+ * ```jsx
+ * // OtherComponent keeps its semantic element (e.g. <h2>).
+ * <VisuallyHidden render={ <OtherComponent /> }>
+ *   Accessible text
+ * </VisuallyHidden>
+ * ```
+ *
+ * The opposite direction is also possible, but be aware that it replaces
+ * the other component's element with VisuallyHidden's default `<div>`:
+ *
+ * ```jsx
+ * // OtherComponent's element becomes a <div>.
+ * <OtherComponent render={ <VisuallyHidden /> }>
+ *   Accessible text
+ * </OtherComponent>
+ * ```
+ *
+ * Choose based on what you need: if the other component's semantic
+ * element matters (e.g. `<label>`, `<legend>`, `<h2>`), keep
+ * `VisuallyHidden` as the host so the element is preserved.
  */
 export const VisuallyHidden = forwardRef< HTMLDivElement, VisuallyHiddenProps >(
 	function VisuallyHidden( { render, ...restProps }, ref ) {