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

package/src/popover/title.tsx

@@ -0,0 +1,47 @@
+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, ...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 { ...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/tabs/context.tsx

@@ -0,0 +1,170 @@
+import {
+	createContext,
+	useContext,
+	useCallback,
+	useMemo,
+	useRef,
+	useEffect,
+} from '@wordpress/element';
+
+type TabsValidationContextType = {
+	registerTab: () => () => void;
+	registerPanel: () => () => void;
+};
+
+/**
+ * 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';
+
+const TabsValidationContext = VALIDATION_ENABLED
+	? createContext< TabsValidationContextType | null >( null )
+	: ( null as unknown as React.Context< TabsValidationContextType | null > );
+
+function useRegisterTabDev() {
+	const context = useContext( TabsValidationContext );
+
+	useEffect( () => {
+		if ( context ) {
+			return context.registerTab();
+		}
+		return undefined;
+	}, [ context ] );
+}
+
+function useRegisterTabProd() {
+	// No-op in production.
+}
+
+/**
+ * Hook that registers a Tab for count validation in development mode.
+ */
+export const useRegisterTab = VALIDATION_ENABLED
+	? useRegisterTabDev
+	: useRegisterTabProd;
+
+function useRegisterPanelDev() {
+	const context = useContext( TabsValidationContext );
+
+	useEffect( () => {
+		if ( context ) {
+			return context.registerPanel();
+		}
+		return undefined;
+	}, [ context ] );
+}
+
+function useRegisterPanelProd() {
+	// No-op in production.
+}
+
+/**
+ * Hook that registers a Panel for count validation in development mode.
+ */
+export const useRegisterPanel = VALIDATION_ENABLED
+	? useRegisterPanelDev
+	: useRegisterPanelProd;
+
+/**
+ * Development-only provider that tracks the number of registered tabs and
+ * panels, and warns when the counts don't match.
+ */
+function TabsValidationProviderDev( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	const tabCountRef = useRef( 0 );
+	const panelCountRef = useRef( 0 );
+	const validationScheduledRef = useRef< ReturnType<
+		typeof setTimeout
+	> | null >( null );
+
+	const scheduleValidation = useCallback( () => {
+		if ( validationScheduledRef.current ) {
+			clearTimeout( validationScheduledRef.current );
+		}
+
+		// Schedule validation for the next tick to allow all
+		// registrations/unregistrations to complete.
+		validationScheduledRef.current = setTimeout( () => {
+			const tabCount = tabCountRef.current;
+			const panelCount = panelCountRef.current;
+
+			if ( tabCount !== panelCount ) {
+				throw new Error(
+					`Tabs: Tab/Panel count mismatch (${ tabCount } Tabs, ${ panelCount } 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.`
+				);
+			}
+
+			validationScheduledRef.current = null;
+		}, 0 );
+	}, [] );
+
+	const registerTab = useCallback( () => {
+		tabCountRef.current += 1;
+		scheduleValidation();
+
+		return () => {
+			tabCountRef.current -= 1;
+			scheduleValidation();
+		};
+	}, [ scheduleValidation ] );
+
+	const registerPanel = useCallback( () => {
+		panelCountRef.current += 1;
+		scheduleValidation();
+
+		return () => {
+			panelCountRef.current -= 1;
+			scheduleValidation();
+		};
+	}, [ scheduleValidation ] );
+
+	useEffect( () => {
+		return () => {
+			if ( validationScheduledRef.current ) {
+				clearTimeout( validationScheduledRef.current );
+			}
+		};
+	}, [] );
+
+	const contextValue = useMemo(
+		() => ( {
+			registerTab,
+			registerPanel,
+		} ),
+		[ registerTab, registerPanel ]
+	);
+
+	return (
+		<TabsValidationContext.Provider value={ contextValue }>
+			{ children }
+		</TabsValidationContext.Provider>
+	);
+}
+
+/**
+ * Production no-op provider that just renders children.
+ */
+function TabsValidationProviderProd( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	return <>{ children }</>;
+}
+
+/**
+ * Provider component that validates the number of tabs matches the number
+ * of panels in development mode.
+ *
+ * In production, this component is a no-op and just renders children.
+ */
+export const TabsValidationProvider = VALIDATION_ENABLED
+	? TabsValidationProviderDev
+	: TabsValidationProviderProd;

package/src/tabs/list.tsx

@@ -21,7 +21,6 @@ export const List = forwardRef< HTMLDivElement, TabListProps >(
 			variant = 'default',
 			className,
 			activateOnFocus,
-			render,
 			...otherProps
 		},
 		forwardedRef

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,11 +119,11 @@
 		align-items: center;
 
 		/* Appearance */
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 
 		/* Typography */
-		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);
 		white-space: nowrap;
 
 		/* Characters in some languages (e.g. Japanese) may have a native higher line-height. */

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/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 */