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

package/src/tabs/panel.tsx

@@ -1,6 +1,7 @@
 import { forwardRef } from '@wordpress/element';
 import clsx from 'clsx';
 import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import { useRegisterPanel } from './context';
 import styles from './style.module.css';
 import type { TabPanelProps } from './types';
 
@@ -12,6 +13,8 @@ import type { TabPanelProps } from './types';
  */
 export const Panel = forwardRef< HTMLDivElement, TabPanelProps >(
 	function TabPanel( { className, ...otherProps }, forwardedRef ) {
+		useRegisterPanel();
+
 		return (
 			<_Tabs.Panel
 				ref={ forwardedRef }

package/src/tabs/root.tsx

@@ -1,5 +1,6 @@
 import { forwardRef } from '@wordpress/element';
 import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import { TabsValidationProvider } from './context';
 import type { TabRootProps } from './types';
 
 /**
@@ -10,6 +11,10 @@ import type { TabRootProps } from './types';
  */
 export const Root = forwardRef< HTMLDivElement, TabRootProps >(
 	function TabsRoot( { ...otherProps }, forwardedRef ) {
-		return <_Tabs.Root ref={ forwardedRef } { ...otherProps } />;
+		return (
+			<TabsValidationProvider>
+				<_Tabs.Root ref={ forwardedRef } { ...otherProps } />
+			</TabsValidationProvider>
+		);
 	}
 );

package/src/tabs/style.module.css

@@ -119,7 +119,7 @@
 		align-items: center;
 
 		/* Appearance */
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 
 		/* Typography */
 		font-family: var(--wpds-font-family-body);

package/src/tabs/tab.tsx

@@ -3,6 +3,7 @@ import clsx from 'clsx';
 import { Tabs as _Tabs } from '@base-ui/react/tabs';
 import { chevronRight } from '@wordpress/icons';
 import { Icon } from '../icon';
+import { useRegisterTab } from './context';
 import styles from './style.module.css';
 import type { TabProps } from './types';
 
@@ -16,6 +17,8 @@ export const Tab = forwardRef< HTMLButtonElement, TabProps >( function Tab(
 	{ className, children, ...otherProps },
 	forwardedRef
 ) {
+	useRegisterTab();
+
 	return (
 		<_Tabs.Tab
 			ref={ forwardedRef }

package/src/tabs/test/index.test.tsx

@@ -2256,5 +2256,167 @@ describe( 'Tabs', () => {
 			);
 		} );
 	} );
+
+	describe( 'Development mode validation', () => {
+		function collectUncaughtErrors() {
+			const errors: Error[] = [];
+			const handler = ( event: ErrorEvent ) => {
+				event.preventDefault();
+				errors.push( event.error );
+			};
+			window.addEventListener( 'error', handler );
+			return {
+				errors,
+				cleanup: () => window.removeEventListener( 'error', handler ),
+			};
+		}
+
+		it( 'should throw when there are more Tabs than Panels', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			render(
+				<Tabs.Root defaultValue="one">
+					<Tabs.List>
+						<Tabs.Tab value="one">One</Tabs.Tab>
+						<Tabs.Tab value="two">Two</Tabs.Tab>
+						<Tabs.Tab value="three">Three</Tabs.Tab>
+					</Tabs.List>
+					<Tabs.Panel value="one">First panel</Tabs.Panel>
+					<Tabs.Panel value="two">Second panel</Tabs.Panel>
+				</Tabs.Root>
+			);
+
+			await waitForComponentToBeInitializedWithSelectedTab( 'One' );
+
+			await waitFor( () => {
+				expect( errors.length ).toBeGreaterThan( 0 );
+			} );
+
+			expect( errors[ 0 ].message ).toBe(
+				'Tabs: Tab/Panel count mismatch (3 Tabs, 2 Panels). Each Tab must be associated with exactly one Panel. Mismatched or missing associations can break screen reader navigation and violate WAI-ARIA Tabs pattern requirements.'
+			);
+
+			cleanup();
+		} );
+
+		it( 'should throw when there are more Panels than Tabs', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			render(
+				<Tabs.Root defaultValue="one">
+					<Tabs.List>
+						<Tabs.Tab value="one">One</Tabs.Tab>
+						<Tabs.Tab value="two">Two</Tabs.Tab>
+					</Tabs.List>
+					<Tabs.Panel value="one">First panel</Tabs.Panel>
+					<Tabs.Panel value="two">Second panel</Tabs.Panel>
+					<Tabs.Panel value="three">Third panel</Tabs.Panel>
+				</Tabs.Root>
+			);
+
+			await waitForComponentToBeInitializedWithSelectedTab( 'One' );
+
+			await waitFor( () => {
+				expect( errors.length ).toBeGreaterThan( 0 );
+			} );
+
+			expect( errors[ 0 ].message ).toBe(
+				'Tabs: Tab/Panel count mismatch (2 Tabs, 3 Panels). Each Tab must be associated with exactly one Panel. Mismatched or missing associations can break screen reader navigation and violate WAI-ARIA Tabs pattern requirements.'
+			);
+
+			cleanup();
+		} );
+
+		it( 'should not throw when Tab and Panel counts match', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			render(
+				<Tabs.Root defaultValue="one">
+					<Tabs.List>
+						<Tabs.Tab value="one">One</Tabs.Tab>
+						<Tabs.Tab value="two">Two</Tabs.Tab>
+					</Tabs.List>
+					<Tabs.Panel value="one">First panel</Tabs.Panel>
+					<Tabs.Panel value="two">Second panel</Tabs.Panel>
+				</Tabs.Root>
+			);
+
+			await waitForComponentToBeInitializedWithSelectedTab( 'One' );
+
+			// Wait a bit to ensure validation has run
+			await new Promise( ( resolve ) => setTimeout( resolve, 50 ) );
+
+			expect( errors ).toHaveLength( 0 );
+
+			cleanup();
+		} );
+
+		it( 'should throw when tabs are used without any panels', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			render(
+				<Tabs.Root>
+					<Tabs.List>
+						<Tabs.Tab value="one">One</Tabs.Tab>
+						<Tabs.Tab value="two">Two</Tabs.Tab>
+					</Tabs.List>
+				</Tabs.Root>
+			);
+
+			await waitFor( () => {
+				expect( errors.length ).toBeGreaterThan( 0 );
+			} );
+
+			expect( errors[ 0 ].message ).toBe(
+				'Tabs: Tab/Panel count mismatch (2 Tabs, 0 Panels). Each Tab must be associated with exactly one Panel. Mismatched or missing associations can break screen reader navigation and violate WAI-ARIA Tabs pattern requirements.'
+			);
+
+			cleanup();
+		} );
+
+		it( 'should detect count mismatch after dynamic changes', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			const { rerender } = render(
+				<Tabs.Root defaultValue="one">
+					<Tabs.List>
+						<Tabs.Tab value="one">One</Tabs.Tab>
+						<Tabs.Tab value="two">Two</Tabs.Tab>
+					</Tabs.List>
+					<Tabs.Panel value="one">First panel</Tabs.Panel>
+					<Tabs.Panel value="two">Second panel</Tabs.Panel>
+				</Tabs.Root>
+			);
+
+			await waitForComponentToBeInitializedWithSelectedTab( 'One' );
+
+			// Wait for validation
+			await new Promise( ( resolve ) => setTimeout( resolve, 50 ) );
+
+			// No errors since counts match
+			expect( errors ).toHaveLength( 0 );
+
+			// Remove a panel to create a mismatch
+			rerender(
+				<Tabs.Root defaultValue="one">
+					<Tabs.List>
+						<Tabs.Tab value="one">One</Tabs.Tab>
+						<Tabs.Tab value="two">Two</Tabs.Tab>
+					</Tabs.List>
+					<Tabs.Panel value="one">First panel</Tabs.Panel>
+				</Tabs.Root>
+			);
+
+			await waitFor( () => {
+				expect( errors.length ).toBeGreaterThan( 0 );
+			} );
+
+			expect( errors[ 0 ].message ).toBe(
+				'Tabs: Tab/Panel count mismatch (2 Tabs, 1 Panels). Each Tab must be associated with exactly one Panel. Mismatched or missing associations can break screen reader navigation and violate WAI-ARIA Tabs pattern requirements.'
+			);
+
+			cleanup();
+		} );
+	} );
 } );
 /* eslint-enable jest/no-conditional-expect */

package/src/tooltip/root.tsx

@@ -1,6 +1,18 @@
 import { Tooltip } from '@base-ui/react/tooltip';
 import type { RootProps } from './types';
 
+/**
+ * `Tooltip` is used to visually show the label of an icon button, or other such interactive controls
+ * that don't have a visual text label.
+ *
+ * Tooltips are not available on touch devices, and thus should not be used for infotips,
+ * descriptions, or dynamic status messages.
+ *
+ * The tooltip itself does not provide any accessible labeling, so when using the
+ * `Tooltip` primitive you must ensure that the trigger is accessibly labeled (e.g. with an `aria-label`).
+ *
+ * See also: [IconButton](https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-iconbutton--docs)
+ */
 function Root( props: RootProps ) {
 	return <Tooltip.Root { ...props } />;
 }

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

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Tooltip } from '../..';
+import { formatBold, formatItalic } from '@wordpress/icons';
+import { Icon, Tooltip } from '../..';
 
 const meta: Meta< typeof Tooltip.Root > = {
 	title: 'Design System/Components/Tooltip',
@@ -16,8 +17,8 @@ export const Default: StoryObj< typeof Tooltip.Root > = {
 	args: {
 		children: (
 			<>
-				<Tooltip.Trigger>Hover me</Tooltip.Trigger>
-				<Tooltip.Popup>Tooltip text</Tooltip.Popup>
+				<Tooltip.Trigger aria-label="Save">💾</Tooltip.Trigger>
+				<Tooltip.Popup>Save</Tooltip.Popup>
 			</>
 		),
 	},
@@ -51,23 +52,23 @@ export const Positioning: StoryObj< typeof Tooltip.Root > = {
 			} }
 		>
 			<Tooltip.Root>
-				<Tooltip.Trigger>Top</Tooltip.Trigger>
-				<Tooltip.Popup side="top">Tooltip on top</Tooltip.Popup>
+				<Tooltip.Trigger aria-label="Up">⬆️</Tooltip.Trigger>
+				<Tooltip.Popup side="top">Up</Tooltip.Popup>
 			</Tooltip.Root>
 
 			<Tooltip.Root>
-				<Tooltip.Trigger>Right</Tooltip.Trigger>
-				<Tooltip.Popup side="right">Tooltip on right</Tooltip.Popup>
+				<Tooltip.Trigger aria-label="Forward">➡️</Tooltip.Trigger>
+				<Tooltip.Popup side="right">Forward</Tooltip.Popup>
 			</Tooltip.Root>
 
 			<Tooltip.Root>
-				<Tooltip.Trigger>Bottom</Tooltip.Trigger>
-				<Tooltip.Popup side="bottom">Tooltip on bottom</Tooltip.Popup>
+				<Tooltip.Trigger aria-label="Down">⬇️</Tooltip.Trigger>
+				<Tooltip.Popup side="bottom">Down</Tooltip.Popup>
 			</Tooltip.Root>
 
 			<Tooltip.Root>
-				<Tooltip.Trigger>Left</Tooltip.Trigger>
-				<Tooltip.Popup side="left">Tooltip on left</Tooltip.Popup>
+				<Tooltip.Trigger aria-label="Back">⬅️</Tooltip.Trigger>
+				<Tooltip.Popup side="left">Back</Tooltip.Popup>
 			</Tooltip.Root>
 		</div>
 	),
@@ -83,13 +84,17 @@ export const WithProvider: StoryObj< typeof Tooltip.Root > = {
 		<Tooltip.Provider delay={ 0 }>
 			<div style={ { display: 'flex', gap: '1rem' } }>
 				<Tooltip.Root>
-					<Tooltip.Trigger>First</Tooltip.Trigger>
-					<Tooltip.Popup>First tooltip</Tooltip.Popup>
+					<Tooltip.Trigger aria-label="Bold">
+						<Icon icon={ formatBold } />
+					</Tooltip.Trigger>
+					<Tooltip.Popup>Bold</Tooltip.Popup>
 				</Tooltip.Root>
 
 				<Tooltip.Root>
-					<Tooltip.Trigger>Second</Tooltip.Trigger>
-					<Tooltip.Popup>Second tooltip</Tooltip.Popup>
+					<Tooltip.Trigger aria-label="Italic">
+						<Icon icon={ formatItalic } />
+					</Tooltip.Trigger>
+					<Tooltip.Popup>Italic</Tooltip.Popup>
 				</Tooltip.Root>
 			</div>
 		</Tooltip.Provider>

package/src/utils/css/item-popup.module.css

@@ -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/use-deprioritized-initial-focus.ts

@@ -0,0 +1,83 @@
+import type { Dialog as _Dialog } from '@base-ui/react/dialog';
+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.).
+ */
+type InitialFocus = _Dialog.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 };
+}