@wordpress/components 28.8.4 → 28.9.0

package/src/composite/legacy/test/index.tsx

@@ -232,7 +232,7 @@ describe.each( [
 				<button>After</button>
 			</>
 		);
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 
 		await press.Tab();
 		expect( screen.getByText( 'Before' ) ).toHaveFocus();
@@ -260,7 +260,7 @@ describe.each( [
 				</Composite>
 			);
 		};
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 
 		const { item1, item2, item3 } = getOneDimensionalItems();
 
@@ -289,7 +289,7 @@ describe.each( [
 				</Composite>
 			);
 		};
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 		const { item1, item2, item3 } = getOneDimensionalItems();
 
 		expect( item2 ).toBeEnabled();
@@ -310,7 +310,7 @@ describe.each( [
 				} ) }
 			/>
 		);
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 		const { item1, item2, item3 } = getOneDimensionalItems();
 
 		expect( item1.id ).toMatch( 'test-id-1' );
@@ -327,7 +327,7 @@ describe.each( [
 				} ) }
 			/>
 		);
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 		const { item2 } = getOneDimensionalItems();
 
 		await press.Tab();
@@ -341,37 +341,37 @@ describe.each( [
 ] )( '%s', ( _when, rtl ) => {
 	const { previous, next, first, last } = getKeys( rtl );
 
-	function useOneDimensionalTest( initialState?: InitialState ) {
+	async function useOneDimensionalTest( initialState?: InitialState ) {
 		const Test = () => (
 			<OneDimensionalTest
 				state={ useCompositeState( { rtl, ...initialState } ) }
 			/>
 		);
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 		return getOneDimensionalItems();
 	}
 
-	function useTwoDimensionalTest( initialState?: InitialState ) {
+	async function useTwoDimensionalTest( initialState?: InitialState ) {
 		const Test = () => (
 			<TwoDimensionalTest
 				state={ useCompositeState( { rtl, ...initialState } ) }
 			/>
 		);
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 		return getTwoDimensionalItems();
 	}
 
-	function useShiftTest( shift: boolean ) {
+	async function useShiftTest( shift: boolean ) {
 		const Test = () => (
 			<ShiftTest state={ useCompositeState( { rtl, shift } ) } />
 		);
-		renderAndValidate( <Test /> );
+		await renderAndValidate( <Test /> );
 		return getShiftTestItems();
 	}
 
 	describe( 'In one dimension', () => {
 		test( 'All directions work with no orientation', async () => {
-			const { item1, item2, item3 } = useOneDimensionalTest();
+			const { item1, item2, item3 } = await useOneDimensionalTest();
 
 			await press.Tab();
 			expect( item1 ).toHaveFocus();
@@ -406,7 +406,7 @@ describe.each( [
 		} );
 
 		test( 'Only left/right work with horizontal orientation', async () => {
-			const { item1, item2, item3 } = useOneDimensionalTest( {
+			const { item1, item2, item3 } = await useOneDimensionalTest( {
 				orientation: 'horizontal',
 			} );
 
@@ -435,7 +435,7 @@ describe.each( [
 		} );
 
 		test( 'Only up/down work with vertical orientation', async () => {
-			const { item1, item2, item3 } = useOneDimensionalTest( {
+			const { item1, item2, item3 } = await useOneDimensionalTest( {
 				orientation: 'vertical',
 			} );
 
@@ -464,7 +464,7 @@ describe.each( [
 		} );
 
 		test( 'Focus wraps with loop enabled', async () => {
-			const { item1, item2, item3 } = useOneDimensionalTest( {
+			const { item1, item2, item3 } = await useOneDimensionalTest( {
 				loop: true,
 			} );
 
@@ -488,7 +488,7 @@ describe.each( [
 	describe( 'In two dimensions', () => {
 		test( 'All directions work as standard', async () => {
 			const { itemA1, itemA2, itemA3, itemB1, itemB2, itemC1, itemC3 } =
-				useTwoDimensionalTest();
+				await useTwoDimensionalTest();
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -524,7 +524,7 @@ describe.each( [
 
 		test( 'Focus wraps around rows/columns with loop enabled', async () => {
 			const { itemA1, itemA2, itemA3, itemB1, itemC1, itemC3 } =
-				useTwoDimensionalTest( { loop: true } );
+				await useTwoDimensionalTest( { loop: true } );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -548,7 +548,7 @@ describe.each( [
 
 		test( 'Focus moves between rows/columns with wrap enabled', async () => {
 			const { itemA1, itemA2, itemA3, itemB1, itemC1, itemC3 } =
-				useTwoDimensionalTest( { wrap: true } );
+				await useTwoDimensionalTest( { wrap: true } );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -577,7 +577,7 @@ describe.each( [
 		} );
 
 		test( 'Focus wraps around start/end with loop and wrap enabled', async () => {
-			const { itemA1, itemC3 } = useTwoDimensionalTest( {
+			const { itemA1, itemC3 } = await useTwoDimensionalTest( {
 				loop: true,
 				wrap: true,
 			} );
@@ -595,7 +595,8 @@ describe.each( [
 		} );
 
 		test( 'Focus shifts if vertical neighbour unavailable when shift enabled', async () => {
-			const { itemA1, itemB1, itemB2, itemC1 } = useShiftTest( true );
+			const { itemA1, itemB1, itemB2, itemC1 } =
+				await useShiftTest( true );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
@@ -616,7 +617,7 @@ describe.each( [
 		} );
 
 		test( 'Focus does not shift if vertical neighbour unavailable when shift not enabled', async () => {
-			const { itemA1, itemB1, itemB2 } = useShiftTest( false );
+			const { itemA1, itemB1, itemB2 } = await useShiftTest( false );
 
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();

package/src/composite/row.tsx

@@ -20,11 +20,11 @@ export const CompositeRow = forwardRef<
 	WordPressComponentProps< CompositeRowProps, 'div', false >
 >( function CompositeRow( props, ref ) {
 	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeRow
-			store={ context.store as Ariakit.CompositeStore }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
+
+	// @ts-expect-error The store prop is undocumented and only used by the
+	// legacy compat layer. The `store` prop is documented, but its type is
+	// obfuscated to discourage its use outside of the component's internals.
+	const store = ( props.store ?? context.store ) as Ariakit.CompositeStore;
+
+	return <Ariakit.CompositeRow store={ store } { ...props } ref={ ref } />;
 } );

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

@@ -13,6 +13,7 @@ import { useContext, useMemo } from '@wordpress/element';
  */
 import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 import { Composite } from '..';
+import { Tooltip } from '../../tooltip';
 
 const meta: Meta< typeof Composite > = {
 	title: 'Components/Composite',
@@ -353,3 +354,44 @@ const Fill = ( { children } ) => {
 		},
 	},
 };
+
+/**
+ * Combining the `Tooltip` and `Composite` component has a few caveats. And while there are a few ways to compose these two components, our recommendation is to render `Composite.Item` as a child of `Tooltip`.
+ *
+ * ```jsx
+ * // 🔴 Does not work
+ * <Composite.Item
+ *   render={
+ *     <Tooltip text="Tooltip">
+ *       <button>Item</button>
+ *     </Tooltip>
+ *   }
+ * />
+ *
+ * // 🟢 Good
+ * <Tooltip text="Tooltip one">
+ *   <Composite.Item>
+ *     Item one
+ *   </Composite.Item>
+ * </Tooltip>
+ * ```
+ */
+export const WithTooltips: StoryObj< typeof Composite > = {
+	...Default,
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Tooltip text="Tooltip one">
+					<Composite.Item>Item one</Composite.Item>
+				</Tooltip>
+				<Tooltip text="Tooltip two">
+					<Composite.Item>Item two</Composite.Item>
+				</Tooltip>
+				<Tooltip text="Tooltip three">
+					<Composite.Item>Item three</Composite.Item>
+				</Tooltip>
+			</>
+		),
+	},
+};

package/src/composite/test/index.tsx

@@ -0,0 +1,123 @@
+/**
+ * External dependencies
+ */
+import { queryByAttribute, render, screen } from '@testing-library/react';
+import { click, press, waitFor } from '@ariakit/test';
+import type { ComponentProps } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { Composite } from '..';
+
+// This is necessary because of how Ariakit calculates page up and
+// page down. Without this, nothing has a height, and so paging up
+// and down doesn't behave as expected in tests.
+
+let clientHeightSpy: jest.SpiedGetter<
+	typeof HTMLElement.prototype.clientHeight
+>;
+
+beforeAll( () => {
+	clientHeightSpy = jest
+		.spyOn( HTMLElement.prototype, 'clientHeight', 'get' )
+		.mockImplementation( function getClientHeight( this: HTMLElement ) {
+			if ( this.tagName === 'BODY' ) {
+				return window.outerHeight;
+			}
+			return 50;
+		} );
+} );
+
+afterAll( () => {
+	clientHeightSpy?.mockRestore();
+} );
+
+async function renderAndValidate( ...args: Parameters< typeof render > ) {
+	const view = render( ...args );
+	await waitFor( () => {
+		const activeButton = queryByAttribute(
+			'data-active-item',
+			view.baseElement,
+			'true'
+		);
+		expect( activeButton ).not.toBeNull();
+	} );
+	return view;
+}
+
+function RemoveItemTest( props: ComponentProps< typeof Composite > ) {
+	const [ showThirdItem, setShowThirdItem ] = useState( true );
+	return (
+		<>
+			<button>Focus trap before composite</button>
+			<Composite { ...props }>
+				<Composite.Item>Item 1</Composite.Item>
+				<Composite.Item>Item 2</Composite.Item>
+				{ showThirdItem && <Composite.Item>Item 3</Composite.Item> }
+			</Composite>
+			<button onClick={ () => setShowThirdItem( ( value ) => ! value ) }>
+				Toggle third item
+			</button>
+		</>
+	);
+}
+
+describe( 'Composite', () => {
+	it( 'should remain focusable even when there are no elements in the DOM associated with the currently active ID', async () => {
+		await renderAndValidate( <RemoveItemTest /> );
+
+		const toggleButton = screen.getByRole( 'button', {
+			name: 'Toggle third item',
+		} );
+
+		await press.Tab();
+		await press.Tab();
+
+		expect(
+			screen.getByRole( 'button', { name: 'Item 1' } )
+		).toHaveFocus();
+
+		await press.ArrowRight();
+		await press.ArrowRight();
+
+		expect(
+			screen.getByRole( 'button', { name: 'Item 3' } )
+		).toHaveFocus();
+
+		await click( toggleButton );
+
+		expect(
+			screen.queryByRole( 'button', { name: 'Item 3' } )
+		).not.toBeInTheDocument();
+
+		await press.ShiftTab();
+
+		expect(
+			screen.getByRole( 'button', { name: 'Item 2' } )
+		).toHaveFocus();
+
+		await click( toggleButton );
+
+		expect(
+			screen.getByRole( 'button', { name: 'Item 3' } )
+		).toBeVisible();
+
+		await press.ShiftTab();
+
+		expect(
+			screen.getByRole( 'button', { name: 'Item 2' } )
+		).toHaveFocus();
+
+		await press.ArrowRight();
+
+		expect(
+			screen.getByRole( 'button', { name: 'Item 3' } )
+		).toHaveFocus();
+	} );
+} );

package/src/composite/typeahead.tsx

@@ -20,11 +20,11 @@ export const CompositeTypeahead = forwardRef<
 	WordPressComponentProps< CompositeTypeaheadProps, 'div', false >
 >( function CompositeTypeahead( props, ref ) {
 	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeTypeahead
-			store={ context.store as Ariakit.CompositeStore }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
+
+	// @ts-expect-error The store prop is undocumented and only used by the
+	// legacy compat layer. The `store` prop is documented, but its type is
+	// obfuscated to discourage its use outside of the component's internals.
+	const store = ( props.store ?? context.store ) as Ariakit.CompositeStore;
+
+	return <Ariakit.CompositeRow store={ store } { ...props } ref={ ref } />;
 } );

package/src/date-time/date/index.tsx

@@ -125,6 +125,7 @@ export function DatePicker( {
 							)
 						);
 					} }
+					size="compact"
 				/>
 				<NavigatorHeading level={ 3 }>
 					<strong>
@@ -150,6 +151,7 @@ export function DatePicker( {
 							)
 						);
 					} }
+					size="compact"
 				/>
 			</Navigator>
 			<Calendar

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

@@ -99,6 +99,7 @@ export const WithMenuItems: StoryObj< typeof Dropdown > = {
 		...Default.args,
 		renderContent: () => (
 			<>
+				<MenuItem>Standalone Item</MenuItem>
 				<MenuGroup label="Group 1">
 					<MenuItem>Item 1</MenuItem>
 					<MenuItem>Item 2</MenuItem>

package/src/dropdown/style.scss

@@ -5,6 +5,16 @@
 .components-dropdown__content {
 	.components-popover__content {
 		padding: $grid-unit-10;
+
+		&:has(.components-menu-group) {
+			padding: 0;
+
+			.components-dropdown-menu__menu > .components-menu-item__button,
+			> .components-menu-item__button {
+				margin: $grid-unit-10;
+				width: auto;
+			}
+		}
 	}
 
 	[role="menuitem"] {
@@ -13,22 +23,9 @@
 
 	.components-menu-group {
 		padding: $grid-unit-10;
-		margin-top: 0;
-		margin-bottom: 0;
-		margin-left: -$grid-unit-10;
-		margin-right: -$grid-unit-10;
-
-		&:first-child {
-			margin-top: -$grid-unit-10;
-		}
-
-		&:last-child {
-			margin-bottom: -$grid-unit-10;
-		}
 	}
 
 	.components-menu-group + .components-menu-group {
-		margin-top: 0;
 		border-top: $border-width solid $gray-400;
 		padding: $grid-unit-10;
 	}

package/src/dropdown-menu/stories/index.story.tsx

@@ -96,6 +96,9 @@ export const WithChildren: StoryObj< typeof DropdownMenu > = {
 		icon: more,
 		children: ( { onClose } ) => (
 			<>
+				<MenuItem icon={ arrowUp } onClick={ onClose }>
+					Standalone Item
+				</MenuItem>
 				<MenuGroup>
 					<MenuItem icon={ arrowUp } onClick={ onClose }>
 						Move Up

package/src/index.ts

@@ -33,14 +33,22 @@ export {
 } from './autocomplete';
 export { default as BaseControl, useBaseControlProps } from './base-control';
 export {
+	/** @deprecated Import `BorderBoxControl` instead. */
 	BorderBoxControl as __experimentalBorderBoxControl,
+	BorderBoxControl,
 	hasSplitBorders as __experimentalHasSplitBorders,
 	isDefinedBorder as __experimentalIsDefinedBorder,
 	isEmptyBorder as __experimentalIsEmptyBorder,
 } from './border-box-control';
-export { BorderControl as __experimentalBorderControl } from './border-control';
 export {
+	/** @deprecated Import `BorderControl` instead. */
+	BorderControl as __experimentalBorderControl,
+	BorderControl,
+} from './border-control';
+export {
+	/** @deprecated Import `BoxControl` instead. */
 	default as __experimentalBoxControl,
+	default as BoxControl,
 	applyValueToSides as __experimentalApplyValueToSides,
 } from './box-control';
 export { default as Button } from './button';
@@ -121,11 +129,21 @@ export { default as __experimentalNavigationGroup } from './navigation/group';
 export { default as __experimentalNavigationItem } from './navigation/item';
 export { default as __experimentalNavigationMenu } from './navigation/menu';
 export {
+	/** @deprecated Import `Navigator` instead. */
 	NavigatorProvider as __experimentalNavigatorProvider,
+	/** @deprecated Import `Navigator` and use `Navigator.Screen` instead. */
 	NavigatorScreen as __experimentalNavigatorScreen,
+	/** @deprecated Import `Navigator` and use `Navigator.Button` instead. */
 	NavigatorButton as __experimentalNavigatorButton,
+	/** @deprecated Import `Navigator` and use `Navigator.BackButton` instead. */
 	NavigatorBackButton as __experimentalNavigatorBackButton,
+	/** @deprecated Import `Navigator` and use `Navigator.BackButton` instead. */
 	NavigatorToParentButton as __experimentalNavigatorToParentButton,
+} from './navigator/legacy';
+export {
+	Navigator,
+	useNavigator,
+	/** @deprecated Import `useNavigator` instead. */
 	useNavigator as __experimentalUseNavigator,
 } from './navigator';
 export { default as Notice } from './notice';

package/src/menu-group/style.scss

@@ -1,5 +1,4 @@
 .components-menu-group + .components-menu-group {
-	margin-top: $grid-unit-10;
 	padding-top: $grid-unit-10;
 	border-top: $border-width solid $gray-900;
 
@@ -10,6 +9,10 @@
 	}
 }
 
+.components-menu-group:has(> div:empty) {
+	display: none;
+}
+
 .components-menu-group__label {
 	padding: 0 $grid-unit-10;
 	margin-top: $grid-unit-05;

package/src/menu-items-choice/style.scss

@@ -1,5 +1,7 @@
 .components-menu-items-choice,
 .components-menu-items-choice.components-button {
+	height: auto;
+
 	svg {
 		margin-right: $grid-unit-15;
 	}