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

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);
 	}
@@ -60,6 +60,7 @@
 		align-items: center;
 		justify-content: flex-start;
 		gap: var(--wpds-dimension-gap-xs);
+		cursor: var(--wpds-cursor-control);
 		min-height: var(--wp-ui-popup-item-height);
 		border-radius: var(--wpds-border-radius-sm);
 		user-select: none;

package/src/utils/css/select-trigger.module.css

@@ -26,6 +26,7 @@
 		font-size: inherit;
 		line-height: 1.4;
 		text-align: start;
+		cursor: var(--wpds-cursor-control);
 		user-select: none;
 
 		&.is-minimal {

package/src/utils/test/use-deprioritized-initial-focus.test.tsx

@@ -0,0 +1,230 @@
+import { render, screen } from '@testing-library/react';
+import { createRef, useEffect } from '@wordpress/element';
+import { useDeprioritizedInitialFocus } from '../use-deprioritized-initial-focus';
+
+const ATTR = 'data-test-deprioritized';
+
+function TestHarness( {
+	initialFocus,
+	onResolved,
+}: {
+	initialFocus?: Parameters<
+		typeof useDeprioritizedInitialFocus
+	>[ 0 ][ 'initialFocus' ];
+	onResolved: (
+		result: ReturnType< typeof useDeprioritizedInitialFocus >
+	) => void;
+} ) {
+	const result = useDeprioritizedInitialFocus( {
+		initialFocus,
+		deprioritizedAttribute: ATTR,
+	} );
+
+	useEffect( () => {
+		onResolved( result );
+	} );
+
+	return (
+		<div ref={ result.popupRef } data-testid="popup">
+			<button { ...{ [ ATTR ]: '' } }>Close</button>
+			<button>Action</button>
+			<input type="text" />
+		</div>
+	);
+}
+
+describe( 'useDeprioritizedInitialFocus', () => {
+	describe( 'passthrough', () => {
+		it( 'passes through false unchanged', () => {
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			render(
+				<TestHarness
+					initialFocus={ false }
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			expect( resolved!.resolvedInitialFocus ).toBe( false );
+		} );
+
+		it( 'passes through a ref unchanged', () => {
+			const ref = createRef< HTMLElement >();
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			render(
+				<TestHarness
+					initialFocus={ ref }
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			expect( resolved!.resolvedInitialFocus ).toBe( ref );
+		} );
+
+		it( 'passes through a custom callback unchanged', () => {
+			const cb = () => true as const;
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			render(
+				<TestHarness
+					initialFocus={ cb }
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			expect( resolved!.resolvedInitialFocus ).toBe( cb );
+		} );
+	} );
+
+	describe( 'default behavior (initialFocus undefined or true)', () => {
+		it.each( [ undefined, true ] )(
+			'returns a callback when initialFocus is %s',
+			( value ) => {
+				let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+				render(
+					<TestHarness
+						initialFocus={ value }
+						onResolved={ ( r ) => {
+							resolved = r;
+						} }
+					/>
+				);
+
+				expect( typeof resolved!.resolvedInitialFocus ).toBe(
+					'function'
+				);
+			}
+		);
+
+		it( 'returns the popup element on touch interactions', () => {
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			render(
+				<TestHarness
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			const callback = resolved!.resolvedInitialFocus as (
+				type: string
+			) => HTMLElement | boolean | null;
+			const result = callback( 'touch' );
+
+			expect( result ).toBe( screen.getByTestId( 'popup' ) );
+		} );
+
+		it( 'skips the deprioritized element on non-touch interactions', () => {
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			render(
+				<TestHarness
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			const callback = resolved!.resolvedInitialFocus as (
+				type: string
+			) => HTMLElement | boolean | null;
+			const result = callback( 'mouse' );
+
+			// Should return the Action button, skipping Close
+			expect( result ).toBeInstanceOf( HTMLButtonElement );
+			expect( result as HTMLButtonElement ).toHaveTextContent( 'Action' );
+		} );
+
+		it( 'falls back to default when only deprioritized elements exist', () => {
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			function OnlyDeprioritized( {
+				onResolved: onResolvedProp,
+			}: {
+				onResolved: (
+					r: ReturnType< typeof useDeprioritizedInitialFocus >
+				) => void;
+			} ) {
+				const result = useDeprioritizedInitialFocus( {
+					initialFocus: undefined,
+					deprioritizedAttribute: ATTR,
+				} );
+
+				useEffect( () => {
+					onResolvedProp( result );
+				} );
+
+				return (
+					<div ref={ result.popupRef } data-testid="popup">
+						<button { ...{ [ ATTR ]: '' } }>Close</button>
+						<p>No other tabbable elements</p>
+					</div>
+				);
+			}
+
+			render(
+				<OnlyDeprioritized
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			const callback = resolved!.resolvedInitialFocus as (
+				type: string
+			) => HTMLElement | boolean | null;
+			const result = callback( 'keyboard' );
+
+			// Falls back to Base UI's default
+			expect( result ).toBe( true );
+		} );
+
+		it( 'returns true when popupRef is not attached', () => {
+			let resolved: ReturnType< typeof useDeprioritizedInitialFocus >;
+
+			function NoRef( {
+				onResolved: onResolvedProp,
+			}: {
+				onResolved: (
+					r: ReturnType< typeof useDeprioritizedInitialFocus >
+				) => void;
+			} ) {
+				const result = useDeprioritizedInitialFocus( {
+					initialFocus: undefined,
+					deprioritizedAttribute: ATTR,
+				} );
+
+				useEffect( () => {
+					onResolvedProp( result );
+				} );
+
+				// Intentionally not attaching popupRef to any element
+				return <div>Nothing</div>;
+			}
+
+			render(
+				<NoRef
+					onResolved={ ( r ) => {
+						resolved = r;
+					} }
+				/>
+			);
+
+			const callback = resolved!.resolvedInitialFocus as (
+				type: string
+			) => HTMLElement | boolean | null;
+
+			expect( callback( 'touch' ) ).toBe( true );
+			expect( callback( 'mouse' ) ).toBe( true );
+		} );
+	} );
+} );

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

@@ -0,0 +1,84 @@
+import type { Popover as _Popover } from '@base-ui/react/popover';
+import { useMemo, useRef } from '@wordpress/element';
+import { tabbable } from 'tabbable';
+
+/**
+ * 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 = _Popover.Popup.Props[ 'initialFocus' ];
+
+/**
+ * Options matching Base UI's internal tabbable configuration.
+ * @see https://github.com/floating-ui/floating-ui/blob/master/packages/react/src/utils/tabbable.ts
+ */
+const getTabbableOptions = () => ( {
+	getShadowRoot: true,
+	displayCheck:
+		typeof ResizeObserver === 'function' &&
+		ResizeObserver.toString().includes( '[native code]' )
+			? ( 'full' as const )
+			: ( 'none' as const ),
+} );
+
+/**
+ * Returns a resolved `initialFocus` value that deprioritizes elements
+ * marked with a given data attribute (e.g. a close icon), and an internal
+ * ref that must be merged onto the popup element.
+ *
+ * When `initialFocus` is `undefined` or `true` (the default behavior),
+ * the hook replaces it with a callback that:
+ * 1. On touch interactions — focuses the popup element itself (preventing
+ *    the virtual keyboard on Android), matching Base UI's default.
+ * 2. On other interactions — returns the first tabbable element that does
+ *    *not* carry `deprioritizedAttribute`. Falls back to Base UI's default
+ *    when the deprioritized element is the only tabbable element.
+ *
+ * All other `initialFocus` values (`false`, `RefObject`, callback) pass
+ * through unchanged.
+ *
+ * @param props
+ * @param props.initialFocus           The consumer-provided `initialFocus` value.
+ * @param props.deprioritizedAttribute The data attribute whose elements should be deprioritized.
+ */
+export function useDeprioritizedInitialFocus( {
+	initialFocus,
+	deprioritizedAttribute,
+}: {
+	initialFocus: InitialFocus;
+	deprioritizedAttribute: string;
+} ) {
+	const popupRef = useRef< HTMLDivElement >( null );
+
+	const resolvedInitialFocus = useMemo( (): InitialFocus => {
+		if ( initialFocus !== undefined && initialFocus !== true ) {
+			return initialFocus;
+		}
+
+		return ( interactionType ): HTMLElement | boolean | null => {
+			if ( interactionType === 'touch' ) {
+				return popupRef.current ?? true;
+			}
+
+			const popup = popupRef.current;
+			if ( ! popup ) {
+				return true;
+			}
+
+			const tabbables = tabbable( popup, getTabbableOptions() );
+			for ( const el of tabbables ) {
+				if (
+					el instanceof HTMLElement &&
+					! el.hasAttribute( deprioritizedAttribute )
+				) {
+					return el;
+				}
+			}
+
+			return true;
+		};
+	}, [ initialFocus, deprioritizedAttribute ] );
+
+	return { resolvedInitialFocus, popupRef };
+}

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 ) {